summaryrefslogtreecommitdiffstats
path: root/third_party/jpeg-xl/lib/include/jxl
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /third_party/jpeg-xl/lib/include/jxl
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'third_party/jpeg-xl/lib/include/jxl')
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/cms.h24
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/cms_interface.h254
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/codestream_header.h430
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/color_encoding.h162
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/decode.h1435
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/decode_cxx.h58
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/encode.h1580
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/encode_cxx.h58
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/memory_manager.h72
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/parallel_runner.h156
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h77
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner_cxx.h65
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/stats.h103
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h71
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner_cxx.h66
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/types.h154
16 files changed, 4765 insertions, 0 deletions
diff --git a/third_party/jpeg-xl/lib/include/jxl/cms.h b/third_party/jpeg-xl/lib/include/jxl/cms.h
new file mode 100644
index 0000000000..6616a2681c
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/cms.h
@@ -0,0 +1,24 @@
+// Copyright (c) the JPEG XL Project Authors. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+#ifndef JXL_CMS_H_
+#define JXL_CMS_H_
+
+// ICC profiles and color space conversions.
+
+#include <jxl/cms_interface.h>
+#include <jxl/jxl_cms_export.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+JXL_CMS_EXPORT const JxlCmsInterface* JxlGetDefaultCms();
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // JXL_CMS_H_
diff --git a/third_party/jpeg-xl/lib/include/jxl/cms_interface.h b/third_party/jpeg-xl/lib/include/jxl/cms_interface.h
new file mode 100644
index 0000000000..c164eaccb5
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/cms_interface.h
@@ -0,0 +1,254 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_color
+ * @{
+ * @file cms_interface.h
+ * @brief Interface to allow the injection of different color management systems
+ * (CMSes, also called color management modules, or CMMs) in JPEG XL.
+ *
+ * A CMS is needed by the JPEG XL encoder and decoder to perform colorspace
+ * conversions. This defines an interface that can be implemented for different
+ * CMSes and then passed to the library.
+ */
+
+#ifndef JXL_CMS_INTERFACE_H_
+#define JXL_CMS_INTERFACE_H_
+
+#include <jxl/color_encoding.h>
+#include <jxl/types.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/** Parses an ICC profile and populates @p c and @p cmyk with the data.
+ *
+ * @param user_data JxlCmsInterface::set_fields_data passed as-is.
+ * @param icc_data the ICC data to parse.
+ * @param icc_size how many bytes of icc_data are valid.
+ * @param c a JxlColorEncoding to populate if applicable.
+ * @param cmyk a boolean to set to whether the colorspace is a CMYK colorspace.
+ * @return Whether the relevant fields in @p c were successfully populated.
+ */
+typedef JXL_BOOL (*jpegxl_cms_set_fields_from_icc_func)(void* user_data,
+ const uint8_t* icc_data,
+ size_t icc_size,
+ JxlColorEncoding* c,
+ JXL_BOOL* cmyk);
+
+/** Represents an input or output colorspace to a color transform, as a
+ * serialized ICC profile. */
+typedef struct {
+ /** The serialized ICC profile. This is guaranteed to be present and valid. */
+ struct {
+ const uint8_t* data;
+ size_t size;
+ } icc;
+
+ /** Structured representation of the colorspace, if applicable. If all fields
+ * are different from their "unknown" value, then this is equivalent to the
+ * ICC representation of the colorspace. If some are "unknown", those that are
+ * not are still valid and can still be used on their own if they are useful.
+ */
+ JxlColorEncoding color_encoding;
+
+ /** Number of components per pixel. This can be deduced from the other
+ * representations of the colorspace but is provided for convenience and
+ * validation. */
+ size_t num_channels;
+} JxlColorProfile;
+
+/** Allocates and returns the data needed for @p num_threads parallel transforms
+ * from the @p input colorspace to @p output, with up to @p pixels_per_thread
+ * pixels to transform per call to JxlCmsInterface::run. @p init_data comes
+ * directly from the JxlCmsInterface instance. Since @c run only receives the
+ * data returned by @c init, a reference to @p init_data should be kept there
+ * if access to it is desired in @c run. Likewise for JxlCmsInterface::destroy.
+ *
+ * The ICC data in @p input and @p output is guaranteed to outlive the @c init /
+ * @c run / @c destroy cycle.
+ *
+ * @param init_data JxlCmsInterface::init_data passed as-is.
+ * @param num_threads the maximum number of threads from which
+ * JxlCmsInterface::run will be called.
+ * @param pixels_per_thread the maximum number of pixels that each call to
+ * JxlCmsInterface::run will have to transform.
+ * @param input_profile the input colorspace for the transform.
+ * @param output_profile the colorspace to which JxlCmsInterface::run should
+ * convert the input data.
+ * @param intensity_target for colorspaces where luminance is relative
+ * (essentially: not PQ), indicates the luminance at which (1, 1, 1) will
+ * be displayed. This is useful for conversions between PQ and a relative
+ * luminance colorspace, in either direction: @p intensity_target cd/m²
+ * in PQ should map to and from (1, 1, 1) in the relative one.\n
+ * It is also used for conversions to and from HLG, as it is
+ * scene-referred while other colorspaces are assumed to be
+ * display-referred. That is, conversions from HLG should apply the OOTF
+ * for a peak display luminance of @p intensity_target, and conversions
+ * to HLG should undo it. The OOTF is a gamma function applied to the
+ * luminance channel (https://www.itu.int/rec/R-REC-BT.2100-2-201807-I
+ * page 7), with the gamma value computed as
+ * <tt>1.2 * 1.111^log2(intensity_target / 1000)</tt> (footnote 2 page 8
+ * of the same document).
+ * @return The data needed for the transform, or @c NULL in case of failure.
+ * This will be passed to the other functions as @c user_data.
+ */
+typedef void* (*jpegxl_cms_init_func)(void* init_data, size_t num_threads,
+ size_t pixels_per_thread,
+ const JxlColorProfile* input_profile,
+ const JxlColorProfile* output_profile,
+ float intensity_target);
+
+/** Returns a buffer that can be used by callers of the interface to store the
+ * input of the conversion or read its result, if they pass it as the input or
+ * output of the @c run function.
+ * @param user_data the data returned by @c init.
+ * @param thread the index of the thread for which to return a buffer.
+ * @return A buffer that can be used by the caller for passing to @c run.
+ */
+typedef float* (*jpegxl_cms_get_buffer_func)(void* user_data, size_t thread);
+
+/** Executes one transform and returns true on success or false on error. It
+ * must be possible to call this from different threads with different values
+ * for @p thread, all between 0 (inclusive) and the value of @p num_threads
+ * passed to @c init (exclusive). It is allowed to implement this by locking
+ * such that the transforms are essentially performed sequentially, if such a
+ * performance profile is acceptable. @p user_data is the data returned by
+ * @c init.
+ * The buffers each contain @p num_pixels × @c num_channels interleaved floating
+ * point (0..1) samples where @c num_channels is the number of color channels of
+ * their respective color profiles. It is guaranteed that the only case in which
+ * they might overlap is if the output has fewer channels than the input, in
+ * which case the pointers may be identical.
+ * For CMYK data, 0 represents the maximum amount of ink while 1 represents no
+ * ink.
+ * @param user_data the data returned by @c init.
+ * @param thread the index of the thread from which the function is being
+ * called.
+ * @param input_buffer the buffer containing the pixel data to be transformed.
+ * @param output_buffer the buffer receiving the transformed pixel data.
+ * @param num_pixels the number of pixels to transform from @p input to
+ * @p output.
+ * @return JXL_TRUE on success, JXL_FALSE on failure.
+ */
+typedef JXL_BOOL (*jpegxl_cms_run_func)(void* user_data, size_t thread,
+ const float* input_buffer,
+ float* output_buffer,
+ size_t num_pixels);
+
+/** Performs the necessary clean-up and frees the memory allocated for user
+ * data.
+ */
+typedef void (*jpegxl_cms_destroy_func)(void*);
+
+/**
+ * Interface for performing colorspace transforms. The @c init function can be
+ * called several times to instantiate several transforms, including before
+ * other transforms have been destroyed.
+ *
+ * The call sequence for a given colorspace transform could look like the
+ * following:
+ * @dot
+ * digraph calls {
+ * newrank = true
+ * node [shape = box, fontname = monospace]
+ * init [label = "user_data <- init(\l\
+ * init_data = data,\l\
+ * num_threads = 3,\l\
+ * pixels_per_thread = 20,\l\
+ * input = (sRGB, 3 channels),\l\
+ * output = (Display-P3, 3 channels),\l\
+ * intensity_target = 255\l\
+ * )\l"]
+ * subgraph cluster_0 {
+ * color = lightgrey
+ * label = "thread 1"
+ * labeljust = "c"
+ * run_1_1 [label = "run(\l\
+ * user_data,\l\
+ * thread = 1,\l\
+ * input = in[0],\l\
+ * output = out[0],\l\
+ * num_pixels = 20\l\
+ * )\l"]
+ * run_1_2 [label = "run(\l\
+ * user_data,\l\
+ * thread = 1,\l\
+ * input = in[3],\l\
+ * output = out[3],\l\
+ * num_pixels = 20\l\
+ * )\l"]
+ * }
+ * subgraph cluster_1 {
+ * color = lightgrey
+ * label = "thread 2"
+ * labeljust = "l"
+ * run_2_1 [label = "run(\l\
+ * user_data,\l\
+ * thread = 2,\l\
+ * input = in[1],\l\
+ * output = out[1],\l\
+ * num_pixels = 20\l\
+ * )\l"]
+ * run_2_2 [label = "run(\l\
+ * user_data,\l\
+ * thread = 2,\l\
+ * input = in[4],\l\
+ * output = out[4],\l\
+ * num_pixels = 13\l\
+ * )\l"]
+ * }
+ * subgraph cluster_3 {
+ * color = lightgrey
+ * label = "thread 3"
+ * labeljust = "c"
+ * run_3_1 [label = "run(\l\
+ * user_data,\l\
+ * thread = 3,\l\
+ * input = in[2],\l\
+ * output = out[2],\l\
+ * num_pixels = 20\l\
+ * )\l"]
+ * }
+ * init -> {run_1_1; run_2_1; run_3_1; rank = same}
+ * run_1_1 -> run_1_2
+ * run_2_1 -> run_2_2
+ * {run_1_2; run_2_2, run_3_1} -> "destroy(user_data)"
+ * }
+ * @enddot
+ */
+typedef struct {
+ /** CMS-specific data that will be passed to @ref set_fields_from_icc. */
+ void* set_fields_data;
+ /** Populates a JxlColorEncoding from an ICC profile. */
+ jpegxl_cms_set_fields_from_icc_func set_fields_from_icc;
+
+ /** CMS-specific data that will be passed to @ref init. */
+ void* init_data;
+ /** Prepares a colorspace transform as described in the documentation of @ref
+ * jpegxl_cms_init_func. */
+ jpegxl_cms_init_func init;
+ /** Returns a buffer that can be used as input to @c run. */
+ jpegxl_cms_get_buffer_func get_src_buf;
+ /** Returns a buffer that can be used as output from @c run. */
+ jpegxl_cms_get_buffer_func get_dst_buf;
+ /** Executes the transform on a batch of pixels, per @ref jpegxl_cms_run_func.
+ */
+ jpegxl_cms_run_func run;
+ /** Cleans up the transform. */
+ jpegxl_cms_destroy_func destroy;
+} JxlCmsInterface;
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_CMS_INTERFACE_H_ */
+
+/** @} */
diff --git a/third_party/jpeg-xl/lib/include/jxl/codestream_header.h b/third_party/jpeg-xl/lib/include/jxl/codestream_header.h
new file mode 100644
index 0000000000..fb71484233
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/codestream_header.h
@@ -0,0 +1,430 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_metadata
+ * @{
+ * @file codestream_header.h
+ * @brief Definitions of structs and enums for the metadata from the JPEG XL
+ * codestream headers (signature, metadata, preview dimensions, ...), excluding
+ * color encoding which is in color_encoding.h.
+ */
+
+#ifndef JXL_CODESTREAM_HEADER_H_
+#define JXL_CODESTREAM_HEADER_H_
+
+#include <jxl/types.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/** Image orientation metadata.
+ * Values 1..8 match the EXIF definitions.
+ * The name indicates the operation to perform to transform from the encoded
+ * image to the display image.
+ */
+typedef enum {
+ JXL_ORIENT_IDENTITY = 1,
+ JXL_ORIENT_FLIP_HORIZONTAL = 2,
+ JXL_ORIENT_ROTATE_180 = 3,
+ JXL_ORIENT_FLIP_VERTICAL = 4,
+ JXL_ORIENT_TRANSPOSE = 5,
+ JXL_ORIENT_ROTATE_90_CW = 6,
+ JXL_ORIENT_ANTI_TRANSPOSE = 7,
+ JXL_ORIENT_ROTATE_90_CCW = 8,
+} JxlOrientation;
+
+/** Given type of an extra channel.
+ */
+typedef enum {
+ JXL_CHANNEL_ALPHA,
+ JXL_CHANNEL_DEPTH,
+ JXL_CHANNEL_SPOT_COLOR,
+ JXL_CHANNEL_SELECTION_MASK,
+ JXL_CHANNEL_BLACK,
+ JXL_CHANNEL_CFA,
+ JXL_CHANNEL_THERMAL,
+ JXL_CHANNEL_RESERVED0,
+ JXL_CHANNEL_RESERVED1,
+ JXL_CHANNEL_RESERVED2,
+ JXL_CHANNEL_RESERVED3,
+ JXL_CHANNEL_RESERVED4,
+ JXL_CHANNEL_RESERVED5,
+ JXL_CHANNEL_RESERVED6,
+ JXL_CHANNEL_RESERVED7,
+ JXL_CHANNEL_UNKNOWN,
+ JXL_CHANNEL_OPTIONAL
+} JxlExtraChannelType;
+
+/** The codestream preview header */
+typedef struct {
+ /** Preview width in pixels */
+ uint32_t xsize;
+
+ /** Preview height in pixels */
+ uint32_t ysize;
+} JxlPreviewHeader;
+
+/** The codestream animation header, optionally present in the beginning of
+ * the codestream, and if it is it applies to all animation frames, unlike
+ * JxlFrameHeader which applies to an individual frame.
+ */
+typedef struct {
+ /** Numerator of ticks per second of a single animation frame time unit */
+ uint32_t tps_numerator;
+
+ /** Denominator of ticks per second of a single animation frame time unit */
+ uint32_t tps_denominator;
+
+ /** Amount of animation loops, or 0 to repeat infinitely */
+ uint32_t num_loops;
+
+ /** Whether animation time codes are present at animation frames in the
+ * codestream */
+ JXL_BOOL have_timecodes;
+} JxlAnimationHeader;
+
+/** Basic image information. This information is available from the file
+ * signature and first part of the codestream header.
+ */
+typedef struct {
+ /* TODO(lode): need additional fields for (transcoded) JPEG? For reusable
+ * fields orientation must be read from Exif APP1. For has_icc_profile: must
+ * look up where ICC profile is guaranteed to be in a JPEG file to be able to
+ * indicate this. */
+
+ /* TODO(lode): make struct packed, and/or make this opaque struct with getter
+ * functions (still separate struct from opaque decoder) */
+
+ /** Whether the codestream is embedded in the container format. If true,
+ * metadata information and extensions may be available in addition to the
+ * codestream.
+ */
+ JXL_BOOL have_container;
+
+ /** Width of the image in pixels, before applying orientation.
+ */
+ uint32_t xsize;
+
+ /** Height of the image in pixels, before applying orientation.
+ */
+ uint32_t ysize;
+
+ /** Original image color channel bit depth.
+ */
+ uint32_t bits_per_sample;
+
+ /** Original image color channel floating point exponent bits, or 0 if they
+ * are unsigned integer. For example, if the original data is half-precision
+ * (binary16) floating point, bits_per_sample is 16 and
+ * exponent_bits_per_sample is 5, and so on for other floating point
+ * precisions.
+ */
+ uint32_t exponent_bits_per_sample;
+
+ /** Upper bound on the intensity level present in the image in nits. For
+ * unsigned integer pixel encodings, this is the brightness of the largest
+ * representable value. The image does not necessarily contain a pixel
+ * actually this bright. An encoder is allowed to set 255 for SDR images
+ * without computing a histogram.
+ * Leaving this set to its default of 0 lets libjxl choose a sensible default
+ * value based on the color encoding.
+ */
+ float intensity_target;
+
+ /** Lower bound on the intensity level present in the image. This may be
+ * loose, i.e. lower than the actual darkest pixel. When tone mapping, a
+ * decoder will map [min_nits, intensity_target] to the display range.
+ */
+ float min_nits;
+
+ /** See the description of @see linear_below.
+ */
+ JXL_BOOL relative_to_max_display;
+
+ /** The tone mapping will leave unchanged (linear mapping) any pixels whose
+ * brightness is strictly below this. The interpretation depends on
+ * relative_to_max_display. If true, this is a ratio [0, 1] of the maximum
+ * display brightness [nits], otherwise an absolute brightness [nits].
+ */
+ float linear_below;
+
+ /** Whether the data in the codestream is encoded in the original color
+ * profile that is attached to the codestream metadata header, or is
+ * encoded in an internally supported absolute color space (which the decoder
+ * can always convert to linear or non-linear sRGB or to XYB). If the original
+ * profile is used, the decoder outputs pixel data in the color space matching
+ * that profile, but doesn't convert it to any other color space. If the
+ * original profile is not used, the decoder only outputs the data as sRGB
+ * (linear if outputting to floating point, nonlinear with standard sRGB
+ * transfer function if outputting to unsigned integers) but will not convert
+ * it to to the original color profile. The decoder also does not convert to
+ * the target display color profile. To convert the pixel data produced by
+ * the decoder to the original color profile, one of the JxlDecoderGetColor*
+ * functions needs to be called with @ref JXL_COLOR_PROFILE_TARGET_DATA to get
+ * the color profile of the decoder output, and then an external CMS can be
+ * used for conversion.
+ * Note that for lossy compression, this should be set to false for most use
+ * cases, and if needed, the image should be converted to the original color
+ * profile after decoding, as described above.
+ */
+ JXL_BOOL uses_original_profile;
+
+ /** Indicates a preview image exists near the beginning of the codestream.
+ * The preview itself or its dimensions are not included in the basic info.
+ */
+ JXL_BOOL have_preview;
+
+ /** Indicates animation frames exist in the codestream. The animation
+ * information is not included in the basic info.
+ */
+ JXL_BOOL have_animation;
+
+ /** Image orientation, value 1-8 matching the values used by JEITA CP-3451C
+ * (Exif version 2.3).
+ */
+ JxlOrientation orientation;
+
+ /** Number of color channels encoded in the image, this is either 1 for
+ * grayscale data, or 3 for colored data. This count does not include
+ * the alpha channel or other extra channels. To check presence of an alpha
+ * channel, such as in the case of RGBA color, check alpha_bits != 0.
+ * If and only if this is 1, the JxlColorSpace in the JxlColorEncoding is
+ * JXL_COLOR_SPACE_GRAY.
+ */
+ uint32_t num_color_channels;
+
+ /** Number of additional image channels. This includes the main alpha channel,
+ * but can also include additional channels such as depth, additional alpha
+ * channels, spot colors, and so on. Information about the extra channels
+ * can be queried with JxlDecoderGetExtraChannelInfo. The main alpha channel,
+ * if it exists, also has its information available in the alpha_bits,
+ * alpha_exponent_bits and alpha_premultiplied fields in this JxlBasicInfo.
+ */
+ uint32_t num_extra_channels;
+
+ /** Bit depth of the encoded alpha channel, or 0 if there is no alpha channel.
+ * If present, matches the alpha_bits value of the JxlExtraChannelInfo
+ * associated with this alpha channel.
+ */
+ uint32_t alpha_bits;
+
+ /** Alpha channel floating point exponent bits, or 0 if they are unsigned. If
+ * present, matches the alpha_bits value of the JxlExtraChannelInfo associated
+ * with this alpha channel. integer.
+ */
+ uint32_t alpha_exponent_bits;
+
+ /** Whether the alpha channel is premultiplied. Only used if there is a main
+ * alpha channel. Matches the alpha_premultiplied value of the
+ * JxlExtraChannelInfo associated with this alpha channel.
+ */
+ JXL_BOOL alpha_premultiplied;
+
+ /** Dimensions of encoded preview image, only used if have_preview is
+ * JXL_TRUE.
+ */
+ JxlPreviewHeader preview;
+
+ /** Animation header with global animation properties for all frames, only
+ * used if have_animation is JXL_TRUE.
+ */
+ JxlAnimationHeader animation;
+
+ /** Intrinsic width of the image.
+ * The intrinsic size can be different from the actual size in pixels
+ * (as given by xsize and ysize) and it denotes the recommended dimensions
+ * for displaying the image, i.e. applications are advised to resample the
+ * decoded image to the intrinsic dimensions.
+ */
+ uint32_t intrinsic_xsize;
+
+ /** Intrinsic height of the image.
+ * The intrinsic size can be different from the actual size in pixels
+ * (as given by xsize and ysize) and it denotes the recommended dimensions
+ * for displaying the image, i.e. applications are advised to resample the
+ * decoded image to the intrinsic dimensions.
+ */
+ uint32_t intrinsic_ysize;
+
+ /** Padding for forwards-compatibility, in case more fields are exposed
+ * in a future version of the library.
+ */
+ uint8_t padding[100];
+} JxlBasicInfo;
+
+/** Information for a single extra channel.
+ */
+typedef struct {
+ /** Given type of an extra channel.
+ */
+ JxlExtraChannelType type;
+
+ /** Total bits per sample for this channel.
+ */
+ uint32_t bits_per_sample;
+
+ /** Floating point exponent bits per channel, or 0 if they are unsigned
+ * integer.
+ */
+ uint32_t exponent_bits_per_sample;
+
+ /** The exponent the channel is downsampled by on each axis.
+ * TODO(lode): expand this comment to match the JPEG XL specification,
+ * specify how to upscale, how to round the size computation, and to which
+ * extra channels this field applies.
+ */
+ uint32_t dim_shift;
+
+ /** Length of the extra channel name in bytes, or 0 if no name.
+ * Excludes null termination character.
+ */
+ uint32_t name_length;
+
+ /** Whether alpha channel uses premultiplied alpha. Only applicable if
+ * type is JXL_CHANNEL_ALPHA.
+ */
+ JXL_BOOL alpha_premultiplied;
+
+ /** Spot color of the current spot channel in linear RGBA. Only applicable if
+ * type is JXL_CHANNEL_SPOT_COLOR.
+ */
+ float spot_color[4];
+
+ /** Only applicable if type is JXL_CHANNEL_CFA.
+ * TODO(lode): add comment about the meaning of this field.
+ */
+ uint32_t cfa_channel;
+} JxlExtraChannelInfo;
+
+/* TODO(lode): add API to get the codestream header extensions. */
+/** Extensions in the codestream header. */
+typedef struct {
+ /** Extension bits. */
+ uint64_t extensions;
+} JxlHeaderExtensions;
+
+/** Frame blend modes.
+ * When decoding, if coalescing is enabled (default), this can be ignored.
+ */
+typedef enum {
+ JXL_BLEND_REPLACE = 0,
+ JXL_BLEND_ADD = 1,
+ JXL_BLEND_BLEND = 2,
+ JXL_BLEND_MULADD = 3,
+ JXL_BLEND_MUL = 4,
+} JxlBlendMode;
+
+/** The information about blending the color channels or a single extra channel.
+ * When decoding, if coalescing is enabled (default), this can be ignored and
+ * the blend mode is considered to be JXL_BLEND_REPLACE.
+ * When encoding, these settings apply to the pixel data given to the encoder.
+ */
+typedef struct {
+ /** Blend mode.
+ */
+ JxlBlendMode blendmode;
+ /** Reference frame ID to use as the 'bottom' layer (0-3).
+ */
+ uint32_t source;
+ /** Which extra channel to use as the 'alpha' channel for blend modes
+ * JXL_BLEND_BLEND and JXL_BLEND_MULADD.
+ */
+ uint32_t alpha;
+ /** Clamp values to [0,1] for the purpose of blending.
+ */
+ JXL_BOOL clamp;
+} JxlBlendInfo;
+
+/** The information about layers.
+ * When decoding, if coalescing is enabled (default), this can be ignored.
+ * When encoding, these settings apply to the pixel data given to the encoder,
+ * the encoder could choose an internal representation that differs.
+ */
+typedef struct {
+ /** Whether cropping is applied for this frame. When decoding, if false,
+ * crop_x0 and crop_y0 are set to zero, and xsize and ysize to the main
+ * image dimensions. When encoding and this is false, those fields are
+ * ignored. When decoding, if coalescing is enabled (default), this is always
+ * false, regardless of the internal encoding in the JPEG XL codestream.
+ */
+ JXL_BOOL have_crop;
+
+ /** Horizontal offset of the frame (can be negative).
+ */
+ int32_t crop_x0;
+
+ /** Vertical offset of the frame (can be negative).
+ */
+ int32_t crop_y0;
+
+ /** Width of the frame (number of columns).
+ */
+ uint32_t xsize;
+
+ /** Height of the frame (number of rows).
+ */
+ uint32_t ysize;
+
+ /** The blending info for the color channels. Blending info for extra channels
+ * has to be retrieved separately using JxlDecoderGetExtraChannelBlendInfo.
+ */
+ JxlBlendInfo blend_info;
+
+ /** After blending, save the frame as reference frame with this ID (0-3).
+ * Special case: if the frame duration is nonzero, ID 0 means "will not be
+ * referenced in the future". This value is not used for the last frame.
+ * When encoding, ID 3 is reserved to frames that are generated internally by
+ * the encoder, and should not be used by applications.
+ */
+ uint32_t save_as_reference;
+} JxlLayerInfo;
+
+/** The header of one displayed frame or non-coalesced layer. */
+typedef struct {
+ /** How long to wait after rendering in ticks. The duration in seconds of a
+ * tick is given by tps_numerator and tps_denominator in JxlAnimationHeader.
+ */
+ uint32_t duration;
+
+ /** SMPTE timecode of the current frame in form 0xHHMMSSFF, or 0. The bits are
+ * interpreted from most-significant to least-significant as hour, minute,
+ * second, and frame. If timecode is nonzero, it is strictly larger than that
+ * of a previous frame with nonzero duration. These values are only available
+ * if have_timecodes in JxlAnimationHeader is JXL_TRUE.
+ * This value is only used if have_timecodes in JxlAnimationHeader is
+ * JXL_TRUE.
+ */
+ uint32_t timecode;
+
+ /** Length of the frame name in bytes, or 0 if no name.
+ * Excludes null termination character. This value is set by the decoder.
+ * For the encoder, this value is ignored and @ref JxlEncoderSetFrameName is
+ * used instead to set the name and the length.
+ */
+ uint32_t name_length;
+
+ /** Indicates this is the last animation frame. This value is set by the
+ * decoder to indicate no further frames follow. For the encoder, it is not
+ * required to set this value and it is ignored, @ref JxlEncoderCloseFrames is
+ * used to indicate the last frame to the encoder instead.
+ */
+ JXL_BOOL is_last;
+
+ /** Information about the layer in case of no coalescing.
+ */
+ JxlLayerInfo layer_info;
+} JxlFrameHeader;
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_CODESTREAM_HEADER_H_ */
+
+/** @}*/
diff --git a/third_party/jpeg-xl/lib/include/jxl/color_encoding.h b/third_party/jpeg-xl/lib/include/jxl/color_encoding.h
new file mode 100644
index 0000000000..928117e8dd
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/color_encoding.h
@@ -0,0 +1,162 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_color
+ * @{
+ * @file color_encoding.h
+ * @brief Color Encoding definitions used by JPEG XL.
+ * All CIE units are for the standard 1931 2 degree observer.
+ */
+
+#ifndef JXL_COLOR_ENCODING_H_
+#define JXL_COLOR_ENCODING_H_
+
+#include <stdint.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/** Color space of the image data. */
+typedef enum {
+ /** Tristimulus RGB */
+ JXL_COLOR_SPACE_RGB,
+ /** Luminance based, the primaries in JxlColorEncoding must be ignored. This
+ * value implies that num_color_channels in JxlBasicInfo is 1, any other value
+ * implies num_color_channels is 3. */
+ JXL_COLOR_SPACE_GRAY,
+ /** XYB (opsin) color space */
+ JXL_COLOR_SPACE_XYB,
+ /** None of the other table entries describe the color space appropriately */
+ JXL_COLOR_SPACE_UNKNOWN,
+} JxlColorSpace;
+
+/** Built-in whitepoints for color encoding. When decoding, the numerical xy
+ * whitepoint value can be read from the JxlColorEncoding white_point field
+ * regardless of the enum value. When encoding, enum values except
+ * JXL_WHITE_POINT_CUSTOM override the numerical fields. Some enum values match
+ * a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)), however the
+ * white point and RGB primaries are separate enums here.
+ */
+typedef enum {
+ /** CIE Standard Illuminant D65: 0.3127, 0.3290 */
+ JXL_WHITE_POINT_D65 = 1,
+ /** White point must be read from the JxlColorEncoding white_point field, or
+ * as ICC profile. This enum value is not an exact match of the corresponding
+ * CICP value. */
+ JXL_WHITE_POINT_CUSTOM = 2,
+ /** CIE Standard Illuminant E (equal-energy): 1/3, 1/3 */
+ JXL_WHITE_POINT_E = 10,
+ /** DCI-P3 from SMPTE RP 431-2: 0.314, 0.351 */
+ JXL_WHITE_POINT_DCI = 11,
+} JxlWhitePoint;
+
+/** Built-in primaries for color encoding. When decoding, the primaries can be
+ * read from the JxlColorEncoding primaries_red_xy, primaries_green_xy and
+ * primaries_blue_xy fields regardless of the enum value. When encoding, the
+ * enum values except JXL_PRIMARIES_CUSTOM override the numerical fields. Some
+ * enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC
+ * 23091-2:2019(E)), however the white point and RGB primaries are separate
+ * enums here.
+ */
+typedef enum {
+ /** The CIE xy values of the red, green and blue primaries are: 0.639998686,
+ 0.330010138; 0.300003784, 0.600003357; 0.150002046, 0.059997204 */
+ JXL_PRIMARIES_SRGB = 1,
+ /** Primaries must be read from the JxlColorEncoding primaries_red_xy,
+ * primaries_green_xy and primaries_blue_xy fields, or as ICC profile. This
+ * enum value is not an exact match of the corresponding CICP value. */
+ JXL_PRIMARIES_CUSTOM = 2,
+ /** As specified in Rec. ITU-R BT.2100-1 */
+ JXL_PRIMARIES_2100 = 9,
+ /** As specified in SMPTE RP 431-2 */
+ JXL_PRIMARIES_P3 = 11,
+} JxlPrimaries;
+
+/** Built-in transfer functions for color encoding. Enum values match a subset
+ * of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)) unless specified
+ * otherwise. */
+typedef enum {
+ /** As specified in SMPTE RP 431-2 */
+ JXL_TRANSFER_FUNCTION_709 = 1,
+ /** None of the other table entries describe the transfer function. */
+ JXL_TRANSFER_FUNCTION_UNKNOWN = 2,
+ /** The gamma exponent is 1 */
+ JXL_TRANSFER_FUNCTION_LINEAR = 8,
+ /** As specified in IEC 61966-2-1 sRGB */
+ JXL_TRANSFER_FUNCTION_SRGB = 13,
+ /** As specified in SMPTE ST 2084 */
+ JXL_TRANSFER_FUNCTION_PQ = 16,
+ /** As specified in SMPTE ST 428-1 */
+ JXL_TRANSFER_FUNCTION_DCI = 17,
+ /** As specified in Rec. ITU-R BT.2100-1 (HLG) */
+ JXL_TRANSFER_FUNCTION_HLG = 18,
+ /** Transfer function follows power law given by the gamma value in
+ JxlColorEncoding. Not a CICP value. */
+ JXL_TRANSFER_FUNCTION_GAMMA = 65535,
+} JxlTransferFunction;
+
+/** Renderig intent for color encoding, as specified in ISO 15076-1:2010 */
+typedef enum {
+ /** vendor-specific */
+ JXL_RENDERING_INTENT_PERCEPTUAL = 0,
+ /** media-relative */
+ JXL_RENDERING_INTENT_RELATIVE,
+ /** vendor-specific */
+ JXL_RENDERING_INTENT_SATURATION,
+ /** ICC-absolute */
+ JXL_RENDERING_INTENT_ABSOLUTE,
+} JxlRenderingIntent;
+
+/** Color encoding of the image as structured information.
+ */
+typedef struct {
+ /** Color space of the image data.
+ */
+ JxlColorSpace color_space;
+
+ /** Built-in white point. If this value is JXL_WHITE_POINT_CUSTOM, must
+ * use the numerical whitepoint values from white_point_xy.
+ */
+ JxlWhitePoint white_point;
+
+ /** Numerical whitepoint values in CIE xy space. */
+ double white_point_xy[2];
+
+ /** Built-in RGB primaries. If this value is JXL_PRIMARIES_CUSTOM, must
+ * use the numerical primaries values below. This field and the custom values
+ * below are unused and must be ignored if the color space is
+ * JXL_COLOR_SPACE_GRAY or JXL_COLOR_SPACE_XYB.
+ */
+ JxlPrimaries primaries;
+
+ /** Numerical red primary values in CIE xy space. */
+ double primaries_red_xy[2];
+
+ /** Numerical green primary values in CIE xy space. */
+ double primaries_green_xy[2];
+
+ /** Numerical blue primary values in CIE xy space. */
+ double primaries_blue_xy[2];
+
+ /** Transfer function if have_gamma is 0 */
+ JxlTransferFunction transfer_function;
+
+ /** Gamma value used when transfer_function is JXL_TRANSFER_FUNCTION_GAMMA
+ */
+ double gamma;
+
+ /** Rendering intent defined for the color profile. */
+ JxlRenderingIntent rendering_intent;
+} JxlColorEncoding;
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_COLOR_ENCODING_H_ */
+
+/** @}*/
diff --git a/third_party/jpeg-xl/lib/include/jxl/decode.h b/third_party/jpeg-xl/lib/include/jxl/decode.h
new file mode 100644
index 0000000000..eaee70fa61
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/decode.h
@@ -0,0 +1,1435 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_decoder
+ * @{
+ * @file decode.h
+ * @brief Decoding API for JPEG XL.
+ */
+
+#ifndef JXL_DECODE_H_
+#define JXL_DECODE_H_
+
+#include <jxl/cms_interface.h>
+#include <jxl/codestream_header.h>
+#include <jxl/color_encoding.h>
+#include <jxl/jxl_export.h>
+#include <jxl/memory_manager.h>
+#include <jxl/parallel_runner.h>
+#include <jxl/types.h>
+#include <jxl/version.h> // TODO(eustas): remove before v1.0
+#include <stddef.h>
+#include <stdint.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/**
+ * Decoder library version.
+ *
+ * @return the decoder library version as an integer:
+ * MAJOR_VERSION * 1000000 + MINOR_VERSION * 1000 + PATCH_VERSION. For example,
+ * version 1.2.3 would return 1002003.
+ */
+JXL_EXPORT uint32_t JxlDecoderVersion(void);
+
+/** The result of @ref JxlSignatureCheck.
+ */
+typedef enum {
+ /** Not enough bytes were passed to determine if a valid signature was found.
+ */
+ JXL_SIG_NOT_ENOUGH_BYTES = 0,
+
+ /** No valid JPEG XL header was found. */
+ JXL_SIG_INVALID = 1,
+
+ /** A valid JPEG XL codestream signature was found, that is a JPEG XL image
+ * without container.
+ */
+ JXL_SIG_CODESTREAM = 2,
+
+ /** A valid container signature was found, that is a JPEG XL image embedded
+ * in a box format container.
+ */
+ JXL_SIG_CONTAINER = 3,
+} JxlSignature;
+
+/**
+ * JPEG XL signature identification.
+ *
+ * Checks if the passed buffer contains a valid JPEG XL signature. The passed @p
+ * buf of size
+ * @p size doesn't need to be a full image, only the beginning of the file.
+ *
+ * @return a flag indicating if a JPEG XL signature was found and what type.
+ * - @ref JXL_SIG_NOT_ENOUGH_BYTES if not enough bytes were passed to
+ * determine if a valid signature is there.
+ * - @ref JXL_SIG_INVALID if no valid signature found for JPEG XL decoding.
+ * - @ref JXL_SIG_CODESTREAM if a valid JPEG XL codestream signature was
+ * found.
+ * - @ref JXL_SIG_CONTAINER if a valid JPEG XL container signature was found.
+ */
+JXL_EXPORT JxlSignature JxlSignatureCheck(const uint8_t* buf, size_t len);
+
+/**
+ * Opaque structure that holds the JPEG XL decoder.
+ *
+ * Allocated and initialized with @ref JxlDecoderCreate().
+ * Cleaned up and deallocated with @ref JxlDecoderDestroy().
+ */
+typedef struct JxlDecoderStruct JxlDecoder;
+
+/**
+ * Creates an instance of @ref JxlDecoder and initializes it.
+ *
+ * @p memory_manager will be used for all the library dynamic allocations made
+ * from this instance. The parameter may be NULL, in which case the default
+ * allocator will be used. See jxl/memory_manager.h for details.
+ *
+ * @param memory_manager custom allocator function. It may be NULL. The memory
+ * manager will be copied internally.
+ * @return @c NULL if the instance can not be allocated or initialized
+ * @return pointer to initialized @ref JxlDecoder otherwise
+ */
+JXL_EXPORT JxlDecoder* JxlDecoderCreate(const JxlMemoryManager* memory_manager);
+
+/**
+ * Re-initializes a @ref JxlDecoder instance, so it can be re-used for decoding
+ * another image. All state and settings are reset as if the object was
+ * newly created with @ref JxlDecoderCreate, but the memory manager is kept.
+ *
+ * @param dec instance to be re-initialized.
+ */
+JXL_EXPORT void JxlDecoderReset(JxlDecoder* dec);
+
+/**
+ * Deinitializes and frees @ref JxlDecoder instance.
+ *
+ * @param dec instance to be cleaned up and deallocated.
+ */
+JXL_EXPORT void JxlDecoderDestroy(JxlDecoder* dec);
+
+/**
+ * Return value for @ref JxlDecoderProcessInput.
+ * The values from @ref JXL_DEC_BASIC_INFO onwards are optional informative
+ * events that can be subscribed to, they are never returned if they
+ * have not been registered with @ref JxlDecoderSubscribeEvents.
+ */
+typedef enum {
+ /** Function call finished successfully, or decoding is finished and there is
+ * nothing more to be done.
+ *
+ * Note that @ref JxlDecoderProcessInput will return JXL_DEC_SUCCESS if all
+ * events that were registered with @ref JxlDecoderSubscribeEvents were
+ * processed, even before the end of the JPEG XL codestream.
+ *
+ * In this case, the return value @ref JxlDecoderReleaseInput will be the same
+ * as it was at the last signaled event. E.g. if JXL_DEC_FULL_IMAGE was
+ * subscribed to, then all bytes from the end of the JPEG XL codestream
+ * (including possible boxes needed for jpeg reconstruction) will be returned
+ * as unprocessed.
+ */
+ JXL_DEC_SUCCESS = 0,
+
+ /** An error occurred, for example invalid input file or out of memory.
+ * TODO(lode): add function to get error information from decoder.
+ */
+ JXL_DEC_ERROR = 1,
+
+ /** The decoder needs more input bytes to continue. Before the next @ref
+ * JxlDecoderProcessInput call, more input data must be set, by calling @ref
+ * JxlDecoderReleaseInput (if input was set previously) and then calling @ref
+ * JxlDecoderSetInput. @ref JxlDecoderReleaseInput returns how many bytes
+ * are not yet processed, before a next call to @ref JxlDecoderProcessInput
+ * all unprocessed bytes must be provided again (the address need not match,
+ * but the contents must), and more bytes must be concatenated after the
+ * unprocessed bytes.
+ * In most cases, @ref JxlDecoderReleaseInput will return no unprocessed bytes
+ * at this event, the only exceptions are if the previously set input ended
+ * within (a) the raw codestream signature, (b) the signature box, (c) a box
+ * header, or (d) the first 4 bytes of a brob, ftyp, or jxlp box. In any of
+ * these cases the number of unprocessed bytes is less than 20.
+ */
+ JXL_DEC_NEED_MORE_INPUT = 2,
+
+ /** The decoder is able to decode a preview image and requests setting a
+ * preview output buffer using @ref JxlDecoderSetPreviewOutBuffer. This occurs
+ * if @ref JXL_DEC_PREVIEW_IMAGE is requested and it is possible to decode a
+ * preview image from the codestream and the preview out buffer was not yet
+ * set. There is maximum one preview image in a codestream.
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * end of the frame header (including ToC) of the preview frame as
+ * unprocessed.
+ */
+ JXL_DEC_NEED_PREVIEW_OUT_BUFFER = 3,
+
+ /** The decoder requests an output buffer to store the full resolution image,
+ * which can be set with @ref JxlDecoderSetImageOutBuffer or with @ref
+ * JxlDecoderSetImageOutCallback. This event re-occurs for new frames if
+ * there are multiple animation frames and requires setting an output again.
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * end of the frame header (including ToC) as unprocessed.
+ */
+ JXL_DEC_NEED_IMAGE_OUT_BUFFER = 5,
+
+ /** The JPEG reconstruction buffer is too small for reconstructed JPEG
+ * codestream to fit. @ref JxlDecoderSetJPEGBuffer must be called again to
+ * make room for remaining bytes. This event may occur multiple times
+ * after @ref JXL_DEC_JPEG_RECONSTRUCTION.
+ */
+ JXL_DEC_JPEG_NEED_MORE_OUTPUT = 6,
+
+ /** The box contents output buffer is too small. @ref JxlDecoderSetBoxBuffer
+ * must be called again to make room for remaining bytes. This event may occur
+ * multiple times after @ref JXL_DEC_BOX.
+ */
+ JXL_DEC_BOX_NEED_MORE_OUTPUT = 7,
+
+ /** Informative event by @ref JxlDecoderProcessInput
+ * "JxlDecoderProcessInput": Basic information such as image dimensions and
+ * extra channels. This event occurs max once per image.
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * end of the basic info as unprocessed (including the last byte of basic info
+ * if it did not end on a byte boundary).
+ */
+ JXL_DEC_BASIC_INFO = 0x40,
+
+ /** Informative event by @ref JxlDecoderProcessInput
+ * "JxlDecoderProcessInput": Color encoding or ICC profile from the
+ * codestream header. This event occurs max once per image and always later
+ * than @ref JXL_DEC_BASIC_INFO and earlier than any pixel data.
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * end of the image header (which is the start of the first frame) as
+ * unprocessed.
+ */
+ JXL_DEC_COLOR_ENCODING = 0x100,
+
+ /** Informative event by @ref JxlDecoderProcessInput
+ * "JxlDecoderProcessInput": Preview image, a small frame, decoded. This
+ * event can only happen if the image has a preview frame encoded. This event
+ * occurs max once for the codestream and always later than @ref
+ * JXL_DEC_COLOR_ENCODING and before @ref JXL_DEC_FRAME.
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * end of the preview frame as unprocessed.
+ */
+ JXL_DEC_PREVIEW_IMAGE = 0x200,
+
+ /** Informative event by @ref JxlDecoderProcessInput
+ * "JxlDecoderProcessInput": Beginning of a frame. @ref
+ * JxlDecoderGetFrameHeader can be used at this point. A note on frames:
+ * a JPEG XL image can have internal frames that are not intended to be
+ * displayed (e.g. used for compositing a final frame), but this only returns
+ * displayed frames, unless @ref JxlDecoderSetCoalescing was set to JXL_FALSE:
+ * in that case, the individual layers are returned, without blending. Note
+ * that even when coalescing is disabled, only frames of type kRegularFrame
+ * are returned; frames of type kReferenceOnly and kLfFrame are always for
+ * internal purposes only and cannot be accessed. A displayed frame either has
+ * an animation duration or is the only or last frame in the image. This event
+ * occurs max once per displayed frame, always later than @ref
+ * JXL_DEC_COLOR_ENCODING, and always earlier than any pixel data. While
+ * JPEG XL supports encoding a single frame as the composition of multiple
+ * internal sub-frames also called frames, this event is not indicated for the
+ * internal frames.
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * end of the frame header (including ToC) as unprocessed.
+ */
+ JXL_DEC_FRAME = 0x400,
+
+ /** Informative event by @ref JxlDecoderProcessInput
+ * "JxlDecoderProcessInput": full frame (or layer, in case coalescing is
+ * disabled) is decoded. @ref JxlDecoderSetImageOutBuffer must be used after
+ * getting the basic image information to be able to get the image pixels, if
+ * not this return status only indicates we're past this point in the
+ * codestream. This event occurs max once per frame.
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * end of the frame (or if @ref JXL_DEC_JPEG_RECONSTRUCTION is subscribed to,
+ * from the end of the last box that is needed for jpeg reconstruction) as
+ * unprocessed.
+ */
+ JXL_DEC_FULL_IMAGE = 0x1000,
+
+ /** Informative event by @ref JxlDecoderProcessInput
+ * "JxlDecoderProcessInput": JPEG reconstruction data decoded. @ref
+ * JxlDecoderSetJPEGBuffer may be used to set a JPEG reconstruction buffer
+ * after getting the JPEG reconstruction data. If a JPEG reconstruction buffer
+ * is set a byte stream identical to the JPEG codestream used to encode the
+ * image will be written to the JPEG reconstruction buffer instead of pixels
+ * to the image out buffer. This event occurs max once per image and always
+ * before @ref JXL_DEC_FULL_IMAGE.
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * end of the 'jbrd' box as unprocessed.
+ */
+ JXL_DEC_JPEG_RECONSTRUCTION = 0x2000,
+
+ /** Informative event by @ref JxlDecoderProcessInput
+ * "JxlDecoderProcessInput": The header of a box of the container format
+ * (BMFF) is decoded. The following API functions related to boxes can be used
+ * after this event:
+ * - @ref JxlDecoderSetBoxBuffer and @ref JxlDecoderReleaseBoxBuffer
+ * "JxlDecoderReleaseBoxBuffer": set and release a buffer to get the box
+ * data.
+ * - @ref JxlDecoderGetBoxType get the 4-character box typename.
+ * - @ref JxlDecoderGetBoxSizeRaw get the size of the box as it appears in
+ * the container file, not decompressed.
+ * - @ref JxlDecoderSetDecompressBoxes to configure whether to get the box
+ * data decompressed, or possibly compressed.
+ *
+ * Boxes can be compressed. This is so when their box type is
+ * "brob". In that case, they have an underlying decompressed box
+ * type and decompressed data. @ref JxlDecoderSetDecompressBoxes allows
+ * configuring which data to get. Decompressing requires
+ * Brotli. @ref JxlDecoderGetBoxType has a flag to get the compressed box
+ * type, which can be "brob", or the decompressed box type. If a box
+ * is not compressed (its compressed type is not "brob"), then
+ * the output decompressed box type and data is independent of what
+ * setting is configured.
+ *
+ * The buffer set with @ref JxlDecoderSetBoxBuffer must be set again for each
+ * next box to be obtained, or can be left unset to skip outputting this box.
+ * The output buffer contains the full box data when the next @ref JXL_DEC_BOX
+ * event or @ref JXL_DEC_SUCCESS occurs. @ref JXL_DEC_BOX occurs for all
+ * boxes, including non-metadata boxes such as the signature box or codestream
+ * boxes. To check whether the box is a metadata type for respectively EXIF,
+ * XMP or JUMBF, use @ref JxlDecoderGetBoxType and check for types "Exif",
+ * "xml " and "jumb" respectively.
+ *
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * start of the box header as unprocessed.
+ */
+ JXL_DEC_BOX = 0x4000,
+
+ /** Informative event by @ref JxlDecoderProcessInput
+ * "JxlDecoderProcessInput": a progressive step in decoding the frame is
+ * reached. When calling @ref JxlDecoderFlushImage at this point, the flushed
+ * image will correspond exactly to this point in decoding, and not yet
+ * contain partial results (such as partially more fine detail) of a next
+ * step. By default, this event will trigger maximum once per frame, when a
+ * 8x8th resolution (DC) image is ready (the image data is still returned at
+ * full resolution, giving upscaled DC). Use @ref
+ * JxlDecoderSetProgressiveDetail to configure more fine-grainedness. The
+ * event is not guaranteed to trigger, not all images have progressive steps
+ * or DC encoded.
+ * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
+ * end of the section that was needed to produce this progressive event as
+ * unprocessed.
+ */
+ JXL_DEC_FRAME_PROGRESSION = 0x8000,
+} JxlDecoderStatus;
+
+/** Types of progressive detail.
+ * Setting a progressive detail with value N implies all progressive details
+ * with smaller or equal value. Currently only the following level of
+ * progressive detail is implemented:
+ * - kDC (which implies kFrames)
+ * - kLastPasses (which implies kDC and kFrames)
+ * - kPasses (which implies kLastPasses, kDC and kFrames)
+ */
+typedef enum {
+ // after completed kRegularFrames
+ kFrames = 0,
+ // after completed DC (1:8)
+ kDC = 1,
+ // after completed AC passes that are the last pass for their resolution
+ // target.
+ kLastPasses = 2,
+ // after completed AC passes that are not the last pass for their resolution
+ // target.
+ kPasses = 3,
+ // during DC frame when lower resolution are completed (1:32, 1:16)
+ kDCProgressive = 4,
+ // after completed groups
+ kDCGroups = 5,
+ // after completed groups
+ kGroups = 6,
+} JxlProgressiveDetail;
+
+/** Rewinds decoder to the beginning. The same input must be given again from
+ * the beginning of the file and the decoder will emit events from the beginning
+ * again. When rewinding (as opposed to @ref JxlDecoderReset), the decoder can
+ * keep state about the image, which it can use to skip to a requested frame
+ * more efficiently with @ref JxlDecoderSkipFrames. Settings such as parallel
+ * runner or subscribed events are kept. After rewind, @ref
+ * JxlDecoderSubscribeEvents can be used again, and it is feasible to leave out
+ * events that were already handled before, such as @ref JXL_DEC_BASIC_INFO
+ * and @ref JXL_DEC_COLOR_ENCODING, since they will provide the same information
+ * as before.
+ * The difference to @ref JxlDecoderReset is that some state is kept, namely
+ * settings set by a call to
+ * - @ref JxlDecoderSetCoalescing,
+ * - @ref JxlDecoderSetDesiredIntensityTarget,
+ * - @ref JxlDecoderSetDecompressBoxes,
+ * - @ref JxlDecoderSetKeepOrientation,
+ * - @ref JxlDecoderSetUnpremultiplyAlpha,
+ * - @ref JxlDecoderSetParallelRunner,
+ * - @ref JxlDecoderSetRenderSpotcolors, and
+ * - @ref JxlDecoderSubscribeEvents.
+ *
+ * @param dec decoder object
+ */
+JXL_EXPORT void JxlDecoderRewind(JxlDecoder* dec);
+
+/** Makes the decoder skip the next `amount` frames. It still needs to process
+ * the input, but will not output the frame events. It can be more efficient
+ * when skipping frames, and even more so when using this after @ref
+ * JxlDecoderRewind. If the decoder is already processing a frame (could
+ * have emitted @ref JXL_DEC_FRAME but not yet @ref JXL_DEC_FULL_IMAGE), it
+ * starts skipping from the next frame. If the amount is larger than the amount
+ * of frames remaining in the image, all remaining frames are skipped. Calling
+ * this function multiple times adds the amount to skip to the already existing
+ * amount.
+ *
+ * A frame here is defined as a frame that without skipping emits events such
+ * as @ref JXL_DEC_FRAME and @ref JXL_DEC_FULL_IMAGE, frames that are internal
+ * to the file format but are not rendered as part of an animation, or are not
+ * the final still frame of a still image, are not counted.
+ *
+ * @param dec decoder object
+ * @param amount the amount of frames to skip
+ */
+JXL_EXPORT void JxlDecoderSkipFrames(JxlDecoder* dec, size_t amount);
+
+/**
+ * Skips processing the current frame. Can be called after frame processing
+ * already started, signaled by a @ref JXL_DEC_NEED_IMAGE_OUT_BUFFER event,
+ * but before the corresponding @ref JXL_DEC_FULL_IMAGE event. The next signaled
+ * event will be another @ref JXL_DEC_FRAME, or @ref JXL_DEC_SUCCESS if there
+ * are no more frames. If pixel data is required from the already processed part
+ * of the frame, @ref JxlDecoderFlushImage must be called before this.
+ *
+ * @param dec decoder object
+ * @return @ref JXL_DEC_SUCCESS if there is a frame to skip, and @ref
+ * JXL_DEC_ERROR if the function was not called during frame processing.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSkipCurrentFrame(JxlDecoder* dec);
+
+/**
+ * Set the parallel runner for multithreading. May only be set before starting
+ * decoding.
+ *
+ * @param dec decoder object
+ * @param parallel_runner function pointer to runner for multithreading. It may
+ * be NULL to use the default, single-threaded, runner. A multithreaded
+ * runner should be set to reach fast performance.
+ * @param parallel_runner_opaque opaque pointer for parallel_runner.
+ * @return @ref JXL_DEC_SUCCESS if the runner was set, @ref JXL_DEC_ERROR
+ * otherwise (the previous runner remains set).
+ */
+JXL_EXPORT JxlDecoderStatus
+JxlDecoderSetParallelRunner(JxlDecoder* dec, JxlParallelRunner parallel_runner,
+ void* parallel_runner_opaque);
+
+/**
+ * Returns a hint indicating how many more bytes the decoder is expected to
+ * need to make @ref JxlDecoderGetBasicInfo available after the next @ref
+ * JxlDecoderProcessInput call. This is a suggested large enough value for
+ * the amount of bytes to provide in the next @ref JxlDecoderSetInput call, but
+ * it is not guaranteed to be an upper bound nor a lower bound. This number does
+ * not include bytes that have already been released from the input. Can be used
+ * before the first @ref JxlDecoderProcessInput call, and is correct the first
+ * time in most cases. If not, @ref JxlDecoderSizeHintBasicInfo can be called
+ * again to get an updated hint.
+ *
+ * @param dec decoder object
+ * @return the size hint in bytes if the basic info is not yet fully decoded.
+ * @return 0 when the basic info is already available.
+ */
+JXL_EXPORT size_t JxlDecoderSizeHintBasicInfo(const JxlDecoder* dec);
+
+/** Select for which informative events, i.e. @ref JXL_DEC_BASIC_INFO, etc., the
+ * decoder should return with a status. It is not required to subscribe to any
+ * events, data can still be requested from the decoder as soon as it available.
+ * By default, the decoder is subscribed to no events (events_wanted == 0), and
+ * the decoder will then only return when it cannot continue because it needs
+ * more input data or more output buffer. This function may only be be called
+ * before using @ref JxlDecoderProcessInput.
+ *
+ * @param dec decoder object
+ * @param events_wanted bitfield of desired events.
+ * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSubscribeEvents(JxlDecoder* dec,
+ int events_wanted);
+
+/** Enables or disables preserving of as-in-bitstream pixeldata
+ * orientation. Some images are encoded with an Orientation tag
+ * indicating that the decoder must perform a rotation and/or
+ * mirroring to the encoded image data.
+ *
+ * - If skip_reorientation is JXL_FALSE (the default): the decoder
+ * will apply the transformation from the orientation setting, hence
+ * rendering the image according to its specified intent. When
+ * producing a JxlBasicInfo, the decoder will always set the
+ * orientation field to JXL_ORIENT_IDENTITY (matching the returned
+ * pixel data) and also align xsize and ysize so that they correspond
+ * to the width and the height of the returned pixel data.
+ * - If skip_reorientation is JXL_TRUE: the decoder will skip
+ * applying the transformation from the orientation setting, returning
+ * the image in the as-in-bitstream pixeldata orientation.
+ * This may be faster to decode since the decoder doesn't have to apply the
+ * transformation, but can cause wrong display of the image if the
+ * orientation tag is not correctly taken into account by the user.
+ *
+ * By default, this option is disabled, and the returned pixel data is
+ * re-oriented according to the image's Orientation setting.
+ *
+ * This function must be called at the beginning, before decoding is performed.
+ *
+ * @see JxlBasicInfo for the orientation field, and @ref JxlOrientation for the
+ * possible values.
+ *
+ * @param dec decoder object
+ * @param skip_reorientation JXL_TRUE to enable, JXL_FALSE to disable.
+ * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus
+JxlDecoderSetKeepOrientation(JxlDecoder* dec, JXL_BOOL skip_reorientation);
+
+/**
+ * Enables or disables preserving of associated alpha channels. If
+ * unpremul_alpha is set to JXL_FALSE then for associated alpha channel, the
+ * pixel data is returned with premultiplied colors. If it is set to JXL_TRUE,
+ * The colors will be unpremultiplied based on the alpha channel. This function
+ * has no effect if the image does not have an associated alpha channel.
+ *
+ * By default, this option is disabled, and the returned pixel data "as is".
+ *
+ * This function must be called at the beginning, before decoding is performed.
+ *
+ * @param dec decoder object
+ * @param unpremul_alpha JXL_TRUE to enable, JXL_FALSE to disable.
+ * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus
+JxlDecoderSetUnpremultiplyAlpha(JxlDecoder* dec, JXL_BOOL unpremul_alpha);
+
+/** Enables or disables rendering spot colors. By default, spot colors
+ * are rendered, which is OK for viewing the decoded image. If render_spotcolors
+ * is JXL_FALSE, then spot colors are not rendered, and have to be retrieved
+ * separately using @ref JxlDecoderSetExtraChannelBuffer. This is useful for
+ * e.g. printing applications.
+ *
+ * @param dec decoder object
+ * @param render_spotcolors JXL_TRUE to enable (default), JXL_FALSE to disable.
+ * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus
+JxlDecoderSetRenderSpotcolors(JxlDecoder* dec, JXL_BOOL render_spotcolors);
+
+/** Enables or disables coalescing of zero-duration frames. By default, frames
+ * are returned with coalescing enabled, i.e. all frames have the image
+ * dimensions, and are blended if needed. When coalescing is disabled, frames
+ * can have arbitrary dimensions, a non-zero crop offset, and blending is not
+ * performed. For display, coalescing is recommended. For loading a multi-layer
+ * still image as separate layers (as opposed to the merged image), coalescing
+ * has to be disabled.
+ *
+ * @param dec decoder object
+ * @param coalescing JXL_TRUE to enable coalescing (default), JXL_FALSE to
+ * disable it.
+ * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetCoalescing(JxlDecoder* dec,
+ JXL_BOOL coalescing);
+
+/**
+ * Decodes JPEG XL file using the available bytes. Requires input has been
+ * set with @ref JxlDecoderSetInput. After @ref JxlDecoderProcessInput, input
+ * can optionally be released with @ref JxlDecoderReleaseInput and then set
+ * again to next bytes in the stream. @ref JxlDecoderReleaseInput returns how
+ * many bytes are not yet processed, before a next call to @ref
+ * JxlDecoderProcessInput all unprocessed bytes must be provided again (the
+ * address need not match, but the contents must), and more bytes may be
+ * concatenated after the unprocessed bytes.
+ *
+ * The returned status indicates whether the decoder needs more input bytes, or
+ * more output buffer for a certain type of output data. No matter what the
+ * returned status is (other than @ref JXL_DEC_ERROR), new information, such
+ * as @ref JxlDecoderGetBasicInfo, may have become available after this call.
+ * When the return value is not @ref JXL_DEC_ERROR or @ref JXL_DEC_SUCCESS, the
+ * decoding requires more @ref JxlDecoderProcessInput calls to continue.
+ *
+ * @param dec decoder object
+ * @return @ref JXL_DEC_SUCCESS when decoding finished and all events handled.
+ * If you still have more unprocessed input data anyway, then you can still
+ * continue by using @ref JxlDecoderSetInput and calling @ref
+ * JxlDecoderProcessInput again, similar to handling @ref
+ * JXL_DEC_NEED_MORE_INPUT. @ref JXL_DEC_SUCCESS can occur instead of @ref
+ * JXL_DEC_NEED_MORE_INPUT when, for example, the input data ended right at
+ * the boundary of a box of the container format, all essential codestream
+ * boxes were already decoded, but extra metadata boxes are still present in
+ * the next data. @ref JxlDecoderProcessInput cannot return success if all
+ * codestream boxes have not been seen yet.
+ * @return @ref JXL_DEC_ERROR when decoding failed, e.g. invalid codestream.
+ * TODO(lode): document the input data mechanism
+ * @return @ref JXL_DEC_NEED_MORE_INPUT when more input data is necessary.
+ * @return @ref JXL_DEC_BASIC_INFO when basic info such as image dimensions is
+ * available and this informative event is subscribed to.
+ * @return @ref JXL_DEC_COLOR_ENCODING when color profile information is
+ * available and this informative event is subscribed to.
+ * @return @ref JXL_DEC_PREVIEW_IMAGE when preview pixel information is
+ * available and output in the preview buffer.
+ * @return @ref JXL_DEC_FULL_IMAGE when all pixel information at highest detail
+ * is available and has been output in the pixel buffer.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderProcessInput(JxlDecoder* dec);
+
+/**
+ * Sets input data for @ref JxlDecoderProcessInput. The data is owned by the
+ * caller and may be used by the decoder until @ref JxlDecoderReleaseInput is
+ * called or the decoder is destroyed or reset so must be kept alive until then.
+ * Cannot be called if @ref JxlDecoderSetInput was already called and @ref
+ * JxlDecoderReleaseInput was not yet called, and cannot be called after @ref
+ * JxlDecoderCloseInput indicating the end of input was called.
+ *
+ * @param dec decoder object
+ * @param data pointer to next bytes to read from
+ * @param size amount of bytes available starting from data
+ * @return @ref JXL_DEC_ERROR if input was already set without releasing or @ref
+ * JxlDecoderCloseInput was already called, @ref JXL_DEC_SUCCESS otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetInput(JxlDecoder* dec,
+ const uint8_t* data,
+ size_t size);
+
+/**
+ * Releases input which was provided with @ref JxlDecoderSetInput. Between @ref
+ * JxlDecoderProcessInput and @ref JxlDecoderReleaseInput, the user may not
+ * alter the data in the buffer. Calling @ref JxlDecoderReleaseInput is required
+ * whenever any input is already set and new input needs to be added with @ref
+ * JxlDecoderSetInput, but is not required before @ref JxlDecoderDestroy or @ref
+ * JxlDecoderReset. Calling @ref JxlDecoderReleaseInput when no input is set is
+ * not an error and returns 0.
+ *
+ * @param dec decoder object
+ * @return The amount of bytes the decoder has not yet processed that are still
+ * remaining in the data set by @ref JxlDecoderSetInput, or 0 if no input is
+ * set or @ref JxlDecoderReleaseInput was already called. For a next call
+ * to @ref JxlDecoderProcessInput, the buffer must start with these
+ * unprocessed bytes. From this value it is possible to infer the position
+ * of certain JPEG XL codestream elements (e.g. end of headers, frame
+ * start/end). See the documentation of individual values of @ref
+ * JxlDecoderStatus for more information.
+ */
+JXL_EXPORT size_t JxlDecoderReleaseInput(JxlDecoder* dec);
+
+/**
+ * Marks the input as finished, indicates that no more @ref JxlDecoderSetInput
+ * will be called. This function allows the decoder to determine correctly if it
+ * should return success, need more input or error in certain cases. For
+ * backwards compatibility with a previous version of the API, using this
+ * function is optional when not using the @ref JXL_DEC_BOX event (the decoder
+ * is able to determine the end of the image frames without marking the end),
+ * but using this function is required when using @ref JXL_DEC_BOX for getting
+ * metadata box contents. This function does not replace @ref
+ * JxlDecoderReleaseInput, that function should still be called if its return
+ * value is needed.
+ *
+ * @ref JxlDecoderCloseInput should be called as soon as all known input bytes
+ * are set (e.g. at the beginning when not streaming but setting all input
+ * at once), before the final @ref JxlDecoderProcessInput calls.
+ *
+ * @param dec decoder object
+ */
+JXL_EXPORT void JxlDecoderCloseInput(JxlDecoder* dec);
+
+/**
+ * Outputs the basic image information, such as image dimensions, bit depth and
+ * all other JxlBasicInfo fields, if available.
+ *
+ * @param dec decoder object
+ * @param info struct to copy the information into, or NULL to only check
+ * whether the information is available through the return value.
+ * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR
+ * in case of other error conditions.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetBasicInfo(const JxlDecoder* dec,
+ JxlBasicInfo* info);
+
+/**
+ * Outputs information for extra channel at the given index. The index must be
+ * smaller than num_extra_channels in the associated JxlBasicInfo.
+ *
+ * @param dec decoder object
+ * @param index index of the extra channel to query.
+ * @param info struct to copy the information into, or NULL to only check
+ * whether the information is available through the return value.
+ * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR
+ * in case of other error conditions.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelInfo(
+ const JxlDecoder* dec, size_t index, JxlExtraChannelInfo* info);
+
+/**
+ * Outputs name for extra channel at the given index in UTF-8. The index must be
+ * smaller than num_extra_channels in the associated JxlBasicInfo. The buffer
+ * for name must have at least name_length + 1 bytes allocated, gotten from
+ * the associated JxlExtraChannelInfo.
+ *
+ * @param dec decoder object
+ * @param index index of the extra channel to query.
+ * @param name buffer to copy the name into
+ * @param size size of the name buffer in bytes
+ * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR
+ * in case of other error conditions.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelName(const JxlDecoder* dec,
+ size_t index,
+ char* name,
+ size_t size);
+
+/** Defines which color profile to get: the profile from the codestream
+ * metadata header, which represents the color profile of the original image,
+ * or the color profile from the pixel data produced by the decoder. Both are
+ * the same if the JxlBasicInfo has uses_original_profile set.
+ */
+typedef enum {
+ /** Get the color profile of the original image from the metadata.
+ */
+ JXL_COLOR_PROFILE_TARGET_ORIGINAL = 0,
+
+ /** Get the color profile of the pixel data the decoder outputs. */
+ JXL_COLOR_PROFILE_TARGET_DATA = 1,
+} JxlColorProfileTarget;
+
+/**
+ * Outputs the color profile as JPEG XL encoded structured data, if available.
+ * This is an alternative to an ICC Profile, which can represent a more limited
+ * amount of color spaces, but represents them exactly through enum values.
+ *
+ * It is often possible to use @ref JxlDecoderGetColorAsICCProfile as an
+ * alternative anyway. The following scenarios are possible:
+ * - The JPEG XL image has an attached ICC Profile, in that case, the encoded
+ * structured data is not available, this function will return an error
+ * status. @ref JxlDecoderGetColorAsICCProfile should be called instead.
+ * - The JPEG XL image has an encoded structured color profile, and it
+ * represents an RGB or grayscale color space. This function will return it.
+ * You can still use @ref JxlDecoderGetColorAsICCProfile as well as an
+ * alternative if desired, though depending on which RGB color space is
+ * represented, the ICC profile may be a close approximation. It is also not
+ * always feasible to deduce from an ICC profile which named color space it
+ * exactly represents, if any, as it can represent any arbitrary space.
+ * HDR color spaces such as those using PQ and HLG are also potentially
+ * problematic, in that: while ICC profiles can encode a transfer function
+ * that happens to approximate those of PQ and HLG (HLG for only one given
+ * system gamma at a time, and necessitating a 3D LUT if gamma is to be
+ * different from 1), they cannot (before ICCv4.4) semantically signal that
+ * this is the color space that they represent. Therefore, they will
+ * typically not actually be interpreted as representing an HDR color space.
+ * This is especially detrimental to PQ which will then be interpreted as if
+ * the maximum signal value represented SDR white instead of 10000 cd/m^2,
+ * meaning that the image will be displayed two orders of magnitude (5-7 EV)
+ * too dim.
+ * - The JPEG XL image has an encoded structured color profile, and it
+ * indicates an unknown or xyb color space. In that case, @ref
+ * JxlDecoderGetColorAsICCProfile is not available.
+ *
+ * When rendering an image on a system where ICC-based color management is used,
+ * @ref JxlDecoderGetColorAsICCProfile should generally be used first as it will
+ * return a ready-to-use profile (with the aforementioned caveat about HDR).
+ * When knowledge about the nominal color space is desired if available, @ref
+ * JxlDecoderGetColorAsEncodedProfile should be used first.
+ *
+ * @param dec decoder object
+ * @param target whether to get the original color profile from the metadata
+ * or the color profile of the decoded pixels.
+ * @param color_encoding struct to copy the information into, or NULL to only
+ * check whether the information is available through the return value.
+ * @return @ref JXL_DEC_SUCCESS if the data is available and returned, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR in
+ * case the encoded structured color profile does not exist in the
+ * codestream.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetColorAsEncodedProfile(
+ const JxlDecoder* dec, JxlColorProfileTarget target,
+ JxlColorEncoding* color_encoding);
+
+/**
+ * Outputs the size in bytes of the ICC profile returned by @ref
+ * JxlDecoderGetColorAsICCProfile, if available, or indicates there is none
+ * available. In most cases, the image will have an ICC profile available, but
+ * if it does not, @ref JxlDecoderGetColorAsEncodedProfile must be used instead.
+ *
+ * @see JxlDecoderGetColorAsEncodedProfile for more information. The ICC
+ * profile is either the exact ICC profile attached to the codestream metadata,
+ * or a close approximation generated from JPEG XL encoded structured data,
+ * depending of what is encoded in the codestream.
+ *
+ * @param dec decoder object
+ * @param target whether to get the original color profile from the metadata
+ * or the color profile of the decoded pixels.
+ * @param size variable to output the size into, or NULL to only check the
+ * return status.
+ * @return @ref JXL_DEC_SUCCESS if the ICC profile is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if the decoder has not yet received enough
+ * input data to determine whether an ICC profile is available or what its
+ * size is, @ref JXL_DEC_ERROR in case the ICC profile is not available and
+ * cannot be generated.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetICCProfileSize(
+ const JxlDecoder* dec, JxlColorProfileTarget target, size_t* size);
+
+/**
+ * Outputs ICC profile if available. The profile is only available if @ref
+ * JxlDecoderGetICCProfileSize returns success. The output buffer must have
+ * at least as many bytes as given by @ref JxlDecoderGetICCProfileSize.
+ *
+ * @param dec decoder object
+ * @param target whether to get the original color profile from the metadata
+ * or the color profile of the decoded pixels.
+ * @param icc_profile buffer to copy the ICC profile into
+ * @param size size of the icc_profile buffer in bytes
+ * @return @ref JXL_DEC_SUCCESS if the profile was successfully returned is
+ * available, @ref JXL_DEC_NEED_MORE_INPUT if not yet available, @ref
+ * JXL_DEC_ERROR if the profile doesn't exist or the output size is not
+ * large enough.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetColorAsICCProfile(
+ const JxlDecoder* dec, JxlColorProfileTarget target, uint8_t* icc_profile,
+ size_t size);
+
+/** Sets the desired output color profile of the decoded image by calling
+ * @ref JxlDecoderSetOutputColorProfile, passing on @c color_encoding and
+ * setting @c icc_data to NULL. See @ref JxlDecoderSetOutputColorProfile for
+ * details.
+ *
+ * @param dec decoder object
+ * @param color_encoding the default color encoding to set
+ * @return @ref JXL_DEC_SUCCESS if the preference was set successfully, @ref
+ * JXL_DEC_ERROR otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreferredColorProfile(
+ JxlDecoder* dec, const JxlColorEncoding* color_encoding);
+
+/** Requests that the decoder perform tone mapping to the peak display luminance
+ * passed as @c desired_intensity_target, if appropriate.
+ * @note This is provided for convenience and the exact tone mapping that is
+ * performed is not meant to be considered authoritative in any way. It may
+ * change from version to version.
+ * @param dec decoder object
+ * @param desired_intensity_target the intended target peak luminance
+ * @return @ref JXL_DEC_SUCCESS if the preference was set successfully, @ref
+ * JXL_DEC_ERROR otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetDesiredIntensityTarget(
+ JxlDecoder* dec, float desired_intensity_target);
+
+/**
+ * Sets the desired output color profile of the decoded image either from a
+ * color encoding or an ICC profile. Valid calls of this function have either @c
+ * color_encoding or @c icc_data set to NULL and @c icc_size must be 0 if and
+ * only if @c icc_data is NULL.
+ *
+ * Depending on whether a color management system (CMS) has been set the
+ * behavior is as follows:
+ *
+ * If a color management system (CMS) has been set with @ref JxlDecoderSetCms,
+ * and the CMS supports output to the desired color encoding or ICC profile,
+ * then it will provide the output in that color encoding or ICC profile. If the
+ * desired color encoding or the ICC is not supported, then an error will be
+ * returned.
+ *
+ * If no CMS has been set with @ref JxlDecoderSetCms, there are two cases:
+ *
+ * (1) Calling this function with a color encoding will convert XYB images to
+ * the desired color encoding. In this case, if the requested color encoding has
+ * a narrower gamut, or the white points differ, then the resulting image can
+ * have significant color distortion. Non-XYB images will not be converted to
+ * the desired color space.
+ *
+ * (2) Calling this function with an ICC profile will result in an error.
+ *
+ * If called with an ICC profile (after a call to @ref JxlDecoderSetCms), the
+ * ICC profile has to be a valid RGB or grayscale color profile.
+ *
+ * Can only be set after the @ref JXL_DEC_COLOR_ENCODING event occurred and
+ * before any other event occurred, and should be used before getting
+ * JXL_COLOR_PROFILE_TARGET_DATA.
+ *
+ * This function must not be called before JxlDecoderSetCms.
+ *
+ * @param dec decoder orbject
+ * @param color_encoding the output color encoding
+ * @param icc_data bytes of the icc profile
+ * @param icc_size size of the icc profile in bytes
+ * @return @ref JXL_DEC_SUCCESS if the color profile was set successfully, @ref
+ * JXL_DEC_ERROR otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetOutputColorProfile(
+ JxlDecoder* dec, const JxlColorEncoding* color_encoding,
+ const uint8_t* icc_data, size_t icc_size);
+
+/**
+ * Sets the color management system (CMS) that will be used for color
+ * conversion (if applicable) during decoding. May only be set before starting
+ * decoding and must not be called after @ref JxlDecoderSetOutputColorProfile.
+ *
+ * See @ref JxlDecoderSetOutputColorProfile for how color conversions are done
+ * depending on whether or not a CMS has been set with @ref JxlDecoderSetCms.
+ *
+ * @param dec decoder object.
+ * @param cms structure representing a CMS implementation. See @ref
+ * JxlCmsInterface for more details.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetCms(JxlDecoder* dec,
+ JxlCmsInterface cms);
+// TODO(firsching): add a function JxlDecoderSetDefaultCms() for setting a
+// default in case libjxl is build with a CMS.
+
+/**
+ * Returns the minimum size in bytes of the preview image output pixel buffer
+ * for the given format. This is the buffer for @ref
+ * JxlDecoderSetPreviewOutBuffer. Requires the preview header information is
+ * available in the decoder.
+ *
+ * @param dec decoder object
+ * @param format format of pixels
+ * @param size output value, buffer size in bytes
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * information not available yet.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderPreviewOutBufferSize(
+ const JxlDecoder* dec, const JxlPixelFormat* format, size_t* size);
+
+/**
+ * Sets the buffer to write the small resolution preview image
+ * to. The size of the buffer must be at least as large as given by @ref
+ * JxlDecoderPreviewOutBufferSize. The buffer follows the format described
+ * by JxlPixelFormat. The preview image dimensions are given by the
+ * JxlPreviewHeader. The buffer is owned by the caller.
+ *
+ * @param dec decoder object
+ * @param format format of pixels. Object owned by user and its contents are
+ * copied internally.
+ * @param buffer buffer type to output the pixel data to
+ * @param size size of buffer in bytes
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * size too small.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreviewOutBuffer(
+ JxlDecoder* dec, const JxlPixelFormat* format, void* buffer, size_t size);
+
+/**
+ * Outputs the information from the frame, such as duration when have_animation.
+ * This function can be called when @ref JXL_DEC_FRAME occurred for the current
+ * frame, even when have_animation in the JxlBasicInfo is JXL_FALSE.
+ *
+ * @param dec decoder object
+ * @param header struct to copy the information into, or NULL to only check
+ * whether the information is available through the return value.
+ * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR in
+ * case of other error conditions.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameHeader(const JxlDecoder* dec,
+ JxlFrameHeader* header);
+
+/**
+ * Outputs name for the current frame. The buffer for name must have at least
+ * name_length + 1 bytes allocated, gotten from the associated JxlFrameHeader.
+ *
+ * @param dec decoder object
+ * @param name buffer to copy the name into
+ * @param size size of the name buffer in bytes, including zero termination
+ * character, so this must be at least JxlFrameHeader.name_length + 1.
+ * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR in
+ * case of other error conditions.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameName(const JxlDecoder* dec,
+ char* name, size_t size);
+
+/**
+ * Outputs the blend information for the current frame for a specific extra
+ * channel. This function can be called when @ref JXL_DEC_FRAME occurred for the
+ * current frame, even when have_animation in the JxlBasicInfo is JXL_FALSE.
+ * This information is only useful if coalescing is disabled; otherwise the
+ * decoder will have performed blending already.
+ *
+ * @param dec decoder object
+ * @param index the index of the extra channel
+ * @param blend_info struct to copy the information into
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelBlendInfo(
+ const JxlDecoder* dec, size_t index, JxlBlendInfo* blend_info);
+
+/**
+ * Returns the minimum size in bytes of the image output pixel buffer for the
+ * given format. This is the buffer for @ref JxlDecoderSetImageOutBuffer.
+ * Requires that the basic image information is available in the decoder in the
+ * case of coalescing enabled (default). In case coalescing is disabled, this
+ * can only be called after the @ref JXL_DEC_FRAME event occurs. In that case,
+ * it will return the size required to store the possibly cropped frame (which
+ * can be larger or smaller than the image dimensions).
+ *
+ * @param dec decoder object
+ * @param format format of the pixels.
+ * @param size output value, buffer size in bytes
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * information not available yet.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderImageOutBufferSize(
+ const JxlDecoder* dec, const JxlPixelFormat* format, size_t* size);
+
+/**
+ * Sets the buffer to write the full resolution image to. This can be set when
+ * the @ref JXL_DEC_FRAME event occurs, must be set when the @ref
+ * JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs, and applies only for the
+ * current frame. The size of the buffer must be at least as large as given
+ * by @ref JxlDecoderImageOutBufferSize. The buffer follows the format described
+ * by JxlPixelFormat. The buffer is owned by the caller.
+ *
+ * @param dec decoder object
+ * @param format format of the pixels. Object owned by user and its contents
+ * are copied internally.
+ * @param buffer buffer type to output the pixel data to
+ * @param size size of buffer in bytes
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * size too small.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetImageOutBuffer(
+ JxlDecoder* dec, const JxlPixelFormat* format, void* buffer, size_t size);
+
+/**
+ * Function type for @ref JxlDecoderSetImageOutCallback.
+ *
+ * The callback may be called simultaneously by different threads when using a
+ * threaded parallel runner, on different pixels.
+ *
+ * @param opaque optional user data, as given to @ref
+ * JxlDecoderSetImageOutCallback.
+ * @param x horizontal position of leftmost pixel of the pixel data.
+ * @param y vertical position of the pixel data.
+ * @param num_pixels amount of pixels included in the pixel data, horizontally.
+ * This is not the same as xsize of the full image, it may be smaller.
+ * @param pixels pixel data as a horizontal stripe, in the format passed to @ref
+ * JxlDecoderSetImageOutCallback. The memory is not owned by the user, and
+ * is only valid during the time the callback is running.
+ */
+typedef void (*JxlImageOutCallback)(void* opaque, size_t x, size_t y,
+ size_t num_pixels, const void* pixels);
+
+/**
+ * Initialization callback for @ref JxlDecoderSetMultithreadedImageOutCallback.
+ *
+ * @param init_opaque optional user data, as given to @ref
+ * JxlDecoderSetMultithreadedImageOutCallback.
+ * @param num_threads maximum number of threads that will call the @c run
+ * callback concurrently.
+ * @param num_pixels_per_thread maximum number of pixels that will be passed in
+ * one call to @c run.
+ * @return a pointer to data that will be passed to the @c run callback, or
+ * @c NULL if initialization failed.
+ */
+typedef void* (*JxlImageOutInitCallback)(void* init_opaque, size_t num_threads,
+ size_t num_pixels_per_thread);
+
+/**
+ * Worker callback for @ref JxlDecoderSetMultithreadedImageOutCallback.
+ *
+ * @param run_opaque user data returned by the @c init callback.
+ * @param thread_id number in `[0, num_threads)` identifying the thread of the
+ * current invocation of the callback.
+ * @param x horizontal position of the first (leftmost) pixel of the pixel data.
+ * @param y vertical position of the pixel data.
+ * @param num_pixels number of pixels in the pixel data. May be less than the
+ * full @c xsize of the image, and will be at most equal to the @c
+ * num_pixels_per_thread that was passed to @c init.
+ * @param pixels pixel data as a horizontal stripe, in the format passed to @ref
+ * JxlDecoderSetMultithreadedImageOutCallback. The data pointed to
+ * remains owned by the caller and is only guaranteed to outlive the current
+ * callback invocation.
+ */
+typedef void (*JxlImageOutRunCallback)(void* run_opaque, size_t thread_id,
+ size_t x, size_t y, size_t num_pixels,
+ const void* pixels);
+
+/**
+ * Destruction callback for @ref JxlDecoderSetMultithreadedImageOutCallback,
+ * called after all invocations of the @c run callback to perform any
+ * appropriate clean-up of the @c run_opaque data returned by @c init.
+ *
+ * @param run_opaque user data returned by the @c init callback.
+ */
+typedef void (*JxlImageOutDestroyCallback)(void* run_opaque);
+
+/**
+ * Sets pixel output callback. This is an alternative to @ref
+ * JxlDecoderSetImageOutBuffer. This can be set when the @ref JXL_DEC_FRAME
+ * event occurs, must be set when the @ref JXL_DEC_NEED_IMAGE_OUT_BUFFER event
+ * occurs, and applies only for the current frame. Only one of @ref
+ * JxlDecoderSetImageOutBuffer or @ref JxlDecoderSetImageOutCallback may be used
+ * for the same frame, not both at the same time.
+ *
+ * The callback will be called multiple times, to receive the image
+ * data in small chunks. The callback receives a horizontal stripe of pixel
+ * data, 1 pixel high, xsize pixels wide, called a scanline. The xsize here is
+ * not the same as the full image width, the scanline may be a partial section,
+ * and xsize may differ between calls. The user can then process and/or copy the
+ * partial scanline to an image buffer. The callback may be called
+ * simultaneously by different threads when using a threaded parallel runner, on
+ * different pixels.
+ *
+ * If @ref JxlDecoderFlushImage is not used, then each pixel will be visited
+ * exactly once by the different callback calls, during processing with one or
+ * more @ref JxlDecoderProcessInput calls. These pixels are decoded to full
+ * detail, they are not part of a lower resolution or lower quality progressive
+ * pass, but the final pass.
+ *
+ * If @ref JxlDecoderFlushImage is used, then in addition each pixel will be
+ * visited zero or one times during the blocking @ref JxlDecoderFlushImage call.
+ * Pixels visited as a result of @ref JxlDecoderFlushImage may represent a lower
+ * resolution or lower quality intermediate progressive pass of the image. Any
+ * visited pixel will be of a quality at least as good or better than previous
+ * visits of this pixel. A pixel may be visited zero times if it cannot be
+ * decoded yet or if it was already decoded to full precision (this behavior is
+ * not guaranteed).
+ *
+ * @param dec decoder object
+ * @param format format of the pixels. Object owned by user; its contents are
+ * copied internally.
+ * @param callback the callback function receiving partial scanlines of pixel
+ * data.
+ * @param opaque optional user data, which will be passed on to the callback,
+ * may be NULL.
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such
+ * as @ref JxlDecoderSetImageOutBuffer already set.
+ */
+JXL_EXPORT JxlDecoderStatus
+JxlDecoderSetImageOutCallback(JxlDecoder* dec, const JxlPixelFormat* format,
+ JxlImageOutCallback callback, void* opaque);
+
+/** Similar to @ref JxlDecoderSetImageOutCallback except that the callback is
+ * allowed an initialization phase during which it is informed of how many
+ * threads will call it concurrently, and those calls are further informed of
+ * which thread they are occurring in.
+ *
+ * @param dec decoder object
+ * @param format format of the pixels. Object owned by user; its contents are
+ * copied internally.
+ * @param init_callback initialization callback.
+ * @param run_callback the callback function receiving partial scanlines of
+ * pixel data.
+ * @param destroy_callback clean-up callback invoked after all calls to @c
+ * run_callback. May be NULL if no clean-up is necessary.
+ * @param init_opaque optional user data passed to @c init_callback, may be NULL
+ * (unlike the return value from @c init_callback which may only be NULL if
+ * initialization failed).
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such
+ * as @ref JxlDecoderSetImageOutBuffer having already been called.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetMultithreadedImageOutCallback(
+ JxlDecoder* dec, const JxlPixelFormat* format,
+ JxlImageOutInitCallback init_callback, JxlImageOutRunCallback run_callback,
+ JxlImageOutDestroyCallback destroy_callback, void* init_opaque);
+
+/**
+ * Returns the minimum size in bytes of an extra channel pixel buffer for the
+ * given format. This is the buffer for @ref JxlDecoderSetExtraChannelBuffer.
+ * Requires the basic image information is available in the decoder.
+ *
+ * @param dec decoder object
+ * @param format format of the pixels. The num_channels value is ignored and is
+ * always treated to be 1.
+ * @param size output value, buffer size in bytes
+ * @param index which extra channel to get, matching the index used in @ref
+ * JxlDecoderGetExtraChannelInfo. Must be smaller than num_extra_channels in
+ * the associated JxlBasicInfo.
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * information not available yet or invalid index.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderExtraChannelBufferSize(
+ const JxlDecoder* dec, const JxlPixelFormat* format, size_t* size,
+ uint32_t index);
+
+/**
+ * Sets the buffer to write an extra channel to. This can be set when
+ * the @ref JXL_DEC_FRAME or @ref JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs,
+ * and applies only for the current frame. The size of the buffer must be at
+ * least as large as given by @ref JxlDecoderExtraChannelBufferSize. The buffer
+ * follows the format described by JxlPixelFormat, but where num_channels is 1.
+ * The buffer is owned by the caller. The amount of extra channels is given by
+ * the num_extra_channels field in the associated JxlBasicInfo, and the
+ * information of individual extra channels can be queried with @ref
+ * JxlDecoderGetExtraChannelInfo. To get multiple extra channels, this function
+ * must be called multiple times, once for each wanted index. Not all images
+ * have extra channels. The alpha channel is an extra channel and can be gotten
+ * as part of the color channels when using an RGBA pixel buffer with @ref
+ * JxlDecoderSetImageOutBuffer, but additionally also can be gotten
+ * separately as extra channel. The color channels themselves cannot be gotten
+ * this way.
+ *
+ *
+ * @param dec decoder object
+ * @param format format of the pixels. Object owned by user and its contents
+ * are copied internally. The num_channels value is ignored and is always
+ * treated to be 1.
+ * @param buffer buffer type to output the pixel data to
+ * @param size size of buffer in bytes
+ * @param index which extra channel to get, matching the index used in @ref
+ * JxlDecoderGetExtraChannelInfo. Must be smaller than num_extra_channels in
+ * the associated JxlBasicInfo.
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * size too small or invalid index.
+ */
+JXL_EXPORT JxlDecoderStatus
+JxlDecoderSetExtraChannelBuffer(JxlDecoder* dec, const JxlPixelFormat* format,
+ void* buffer, size_t size, uint32_t index);
+
+/**
+ * Sets output buffer for reconstructed JPEG codestream.
+ *
+ * The data is owned by the caller and may be used by the decoder until @ref
+ * JxlDecoderReleaseJPEGBuffer is called or the decoder is destroyed or
+ * reset so must be kept alive until then.
+ *
+ * If a JPEG buffer was set before and released with @ref
+ * JxlDecoderReleaseJPEGBuffer, bytes that the decoder has already output
+ * should not be included, only the remaining bytes output must be set.
+ *
+ * @param dec decoder object
+ * @param data pointer to next bytes to write to
+ * @param size amount of bytes available starting from data
+ * @return @ref JXL_DEC_ERROR if output buffer was already set and @ref
+ * JxlDecoderReleaseJPEGBuffer was not called on it, @ref JXL_DEC_SUCCESS
+ * otherwise
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetJPEGBuffer(JxlDecoder* dec,
+ uint8_t* data, size_t size);
+
+/**
+ * Releases buffer which was provided with @ref JxlDecoderSetJPEGBuffer.
+ *
+ * Calling @ref JxlDecoderReleaseJPEGBuffer is required whenever
+ * a buffer is already set and a new buffer needs to be added with @ref
+ * JxlDecoderSetJPEGBuffer, but is not required before @ref
+ * JxlDecoderDestroy or @ref JxlDecoderReset.
+ *
+ * Calling @ref JxlDecoderReleaseJPEGBuffer when no buffer is set is
+ * not an error and returns 0.
+ *
+ * @param dec decoder object
+ * @return the amount of bytes the decoder has not yet written to of the data
+ * set by @ref JxlDecoderSetJPEGBuffer, or 0 if no buffer is set or @ref
+ * JxlDecoderReleaseJPEGBuffer was already called.
+ */
+JXL_EXPORT size_t JxlDecoderReleaseJPEGBuffer(JxlDecoder* dec);
+
+/**
+ * Sets output buffer for box output codestream.
+ *
+ * The data is owned by the caller and may be used by the decoder until @ref
+ * JxlDecoderReleaseBoxBuffer is called or the decoder is destroyed or
+ * reset so must be kept alive until then.
+ *
+ * If for the current box a box buffer was set before and released with @ref
+ * JxlDecoderReleaseBoxBuffer, bytes that the decoder has already output
+ * should not be included, only the remaining bytes output must be set.
+ *
+ * The @ref JxlDecoderReleaseBoxBuffer must be used at the next @ref JXL_DEC_BOX
+ * event or final @ref JXL_DEC_SUCCESS event to compute the size of the output
+ * box bytes.
+ *
+ * @param dec decoder object
+ * @param data pointer to next bytes to write to
+ * @param size amount of bytes available starting from data
+ * @return @ref JXL_DEC_ERROR if output buffer was already set and @ref
+ * JxlDecoderReleaseBoxBuffer was not called on it, @ref JXL_DEC_SUCCESS
+ * otherwise
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetBoxBuffer(JxlDecoder* dec,
+ uint8_t* data, size_t size);
+
+/**
+ * Releases buffer which was provided with @ref JxlDecoderSetBoxBuffer.
+ *
+ * Calling @ref JxlDecoderReleaseBoxBuffer is required whenever
+ * a buffer is already set and a new buffer needs to be added with @ref
+ * JxlDecoderSetBoxBuffer, but is not required before @ref
+ * JxlDecoderDestroy or @ref JxlDecoderReset.
+ *
+ * Calling @ref JxlDecoderReleaseBoxBuffer when no buffer is set is
+ * not an error and returns 0.
+ *
+ * @param dec decoder object
+ * @return the amount of bytes the decoder has not yet written to of the data
+ * set by @ref JxlDecoderSetBoxBuffer, or 0 if no buffer is set or @ref
+ * JxlDecoderReleaseBoxBuffer was already called.
+ */
+JXL_EXPORT size_t JxlDecoderReleaseBoxBuffer(JxlDecoder* dec);
+
+/**
+ * Configures whether to get boxes in raw mode or in decompressed mode. In raw
+ * mode, boxes are output as their bytes appear in the container file, which may
+ * be decompressed, or compressed if their type is "brob". In decompressed mode,
+ * "brob" boxes are decompressed with Brotli before outputting them. The size of
+ * the decompressed stream is not known before the decompression has already
+ * finished.
+ *
+ * The default mode is raw. This setting can only be changed before decoding, or
+ * directly after a @ref JXL_DEC_BOX event, and is remembered until the decoder
+ * is reset or destroyed.
+ *
+ * Enabling decompressed mode requires Brotli support from the library.
+ *
+ * @param dec decoder object
+ * @param decompress JXL_TRUE to transparently decompress, JXL_FALSE to get
+ * boxes in raw mode.
+ * @return @ref JXL_DEC_ERROR if decompressed mode is set and Brotli is not
+ * available, @ref JXL_DEC_SUCCESS otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderSetDecompressBoxes(JxlDecoder* dec,
+ JXL_BOOL decompress);
+
+/**
+ * Outputs the type of the current box, after a @ref JXL_DEC_BOX event occurred,
+ * as 4 characters without null termination character. In case of a compressed
+ * "brob" box, this will return "brob" if the decompressed argument is
+ * JXL_FALSE, or the underlying box type if the decompressed argument is
+ * JXL_TRUE.
+ *
+ * The following box types are currently described in ISO/IEC 18181-2:
+ * - "Exif": a box with EXIF metadata. Starts with a 4-byte tiff header offset
+ * (big-endian uint32) that indicates the start of the actual EXIF data
+ * (which starts with a tiff header). Usually the offset will be zero and the
+ * EXIF data starts immediately after the offset field. The Exif orientation
+ * should be ignored by applications; the JPEG XL codestream orientation
+ * takes precedence and libjxl will by default apply the correct orientation
+ * automatically (see @ref JxlDecoderSetKeepOrientation).
+ * - "xml ": a box with XML data, in particular XMP metadata.
+ * - "jumb": a JUMBF superbox (JPEG Universal Metadata Box Format, ISO/IEC
+ * 19566-5).
+ * - "JXL ": mandatory signature box, must come first, 12 bytes long including
+ * the box header
+ * - "ftyp": a second mandatory signature box, must come second, 20 bytes long
+ * including the box header
+ * - "jxll": a JXL level box. This indicates if the codestream is level 5 or
+ * level 10 compatible. If not present, it is level 5. Level 10 allows more
+ * features such as very high image resolution and bit-depths above 16 bits
+ * per channel. Added automatically by the encoder when
+ * JxlEncoderSetCodestreamLevel is used
+ * - "jxlc": a box with the image codestream, in case the codestream is not
+ * split across multiple boxes. The codestream contains the JPEG XL image
+ * itself, including the basic info such as image dimensions, ICC color
+ * profile, and all the pixel data of all the image frames.
+ * - "jxlp": a codestream box in case it is split across multiple boxes.
+ * The contents are the same as in case of a jxlc box, when concatenated.
+ * - "brob": a Brotli-compressed box, which otherwise represents an existing
+ * type of box such as Exif or "xml ". When @ref JxlDecoderSetDecompressBoxes
+ * is set to JXL_TRUE, these boxes will be transparently decompressed by the
+ * decoder.
+ * - "jxli": frame index box, can list the keyframes in case of a JPEG XL
+ * animation allowing the decoder to jump to individual frames more
+ * efficiently.
+ * - "jbrd": JPEG reconstruction box, contains the information required to
+ * byte-for-byte losslessly recontruct a JPEG-1 image. The JPEG DCT
+ * coefficients (pixel content) themselves as well as the ICC profile are
+ * encoded in the JXL codestream (jxlc or jxlp) itself. EXIF, XMP and JUMBF
+ * metadata is encoded in the corresponding boxes. The jbrd box itself
+ * contains information such as the remaining app markers of the JPEG-1 file
+ * and everything else required to fit the information together into the
+ * exact original JPEG file.
+ *
+ * Other application-specific boxes can exist. Their typename should not begin
+ * with "jxl" or "JXL" or conflict with other existing typenames.
+ *
+ * The signature, jxl* and jbrd boxes are processed by the decoder and would
+ * typically be ignored by applications. The typical way to use this function is
+ * to check if an encountered box contains metadata that the application is
+ * interested in (e.g. EXIF or XMP metadata), in order to conditionally set a
+ * box buffer.
+ *
+ * @param dec decoder object
+ * @param type buffer to copy the type into
+ * @param decompressed which box type to get: JXL_FALSE to get the raw box type,
+ * which can be "brob", JXL_TRUE, get the underlying box type.
+ * @return @ref JXL_DEC_SUCCESS if the value is available, @ref JXL_DEC_ERROR if
+ * not, for example the JXL file does not use the container format.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxType(JxlDecoder* dec,
+ JxlBoxType type,
+ JXL_BOOL decompressed);
+
+/**
+ * Returns the size of a box as it appears in the container file, after the @ref
+ * JXL_DEC_BOX event. This includes all the box headers.
+ *
+ * @param dec decoder object
+ * @param size raw size of the box in bytes
+ * @return @ref JXL_DEC_ERROR if no box size is available, @ref JXL_DEC_SUCCESS
+ * otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxSizeRaw(const JxlDecoder* dec,
+ uint64_t* size);
+
+/**
+ * Configures at which progressive steps in frame decoding these @ref
+ * JXL_DEC_FRAME_PROGRESSION event occurs. The default value for the level
+ * of detail if this function is never called is `kDC`.
+ *
+ * @param dec decoder object
+ * @param detail at which level of detail to trigger @ref
+ * JXL_DEC_FRAME_PROGRESSION
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * an invalid value for the progressive detail.
+ */
+JXL_EXPORT JxlDecoderStatus
+JxlDecoderSetProgressiveDetail(JxlDecoder* dec, JxlProgressiveDetail detail);
+
+/**
+ * Returns the intended downsampling ratio for the progressive frame produced
+ * by @ref JxlDecoderFlushImage after the latest @ref JXL_DEC_FRAME_PROGRESSION
+ * event.
+ *
+ * @param dec decoder object
+ * @return The intended downsampling ratio, can be 1, 2, 4 or 8.
+ */
+JXL_EXPORT size_t JxlDecoderGetIntendedDownsamplingRatio(JxlDecoder* dec);
+
+/**
+ * Outputs progressive step towards the decoded image so far when only partial
+ * input was received. If the flush was successful, the buffer set with @ref
+ * JxlDecoderSetImageOutBuffer will contain partial image data.
+ *
+ * Can be called when @ref JxlDecoderProcessInput returns @ref
+ * JXL_DEC_NEED_MORE_INPUT, after the @ref JXL_DEC_FRAME event already occurred
+ * and before the @ref JXL_DEC_FULL_IMAGE event occurred for a frame.
+ *
+ * @param dec decoder object
+ * @return @ref JXL_DEC_SUCCESS if image data was flushed to the output buffer,
+ * or @ref JXL_DEC_ERROR when no flush was done, e.g. if not enough image
+ * data was available yet even for flush, or no output buffer was set yet.
+ * This error is not fatal, it only indicates no flushed image is available
+ * right now. Regular decoding can still be performed.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderFlushImage(JxlDecoder* dec);
+
+/**
+ * Sets the bit depth of the output buffer or callback.
+ *
+ * Can be called after @ref JxlDecoderSetImageOutBuffer or @ref
+ * JxlDecoderSetImageOutCallback. For float pixel data types, only the default
+ * @ref JXL_BIT_DEPTH_FROM_PIXEL_FORMAT setting is supported.
+ *
+ * @param dec decoder object
+ * @param bit_depth the bit depth setting of the pixel output
+ * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * incompatible custom bit depth and pixel data type.
+ */
+JXL_EXPORT JxlDecoderStatus
+JxlDecoderSetImageOutBitDepth(JxlDecoder* dec, const JxlBitDepth* bit_depth);
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_DECODE_H_ */
+
+/** @}*/
diff --git a/third_party/jpeg-xl/lib/include/jxl/decode_cxx.h b/third_party/jpeg-xl/lib/include/jxl/decode_cxx.h
new file mode 100644
index 0000000000..94d2fad83d
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/decode_cxx.h
@@ -0,0 +1,58 @@
+// Copyright (c) the JPEG XL Project Authors. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/// @addtogroup libjxl_cpp
+/// @{
+///
+/// @file decode_cxx.h
+/// @brief C++ header-only helper for @ref decode.h.
+///
+/// There's no binary library associated with the header since this is a header
+/// only library.
+
+#ifndef JXL_DECODE_CXX_H_
+#define JXL_DECODE_CXX_H_
+
+#include <jxl/decode.h>
+#include <jxl/memory_manager.h>
+
+#include <memory>
+
+#if !(defined(__cplusplus) || defined(c_plusplus))
+#error "This a C++ only header. Use jxl/decode.h from C sources."
+#endif
+
+/// Struct to call JxlDecoderDestroy from the JxlDecoderPtr unique_ptr.
+struct JxlDecoderDestroyStruct {
+ /// Calls @ref JxlDecoderDestroy() on the passed decoder.
+ void operator()(JxlDecoder* decoder) { JxlDecoderDestroy(decoder); }
+};
+
+/// std::unique_ptr<> type that calls JxlDecoderDestroy() when releasing the
+/// decoder.
+///
+/// Use this helper type from C++ sources to ensure the decoder is destroyed and
+/// their internal resources released.
+typedef std::unique_ptr<JxlDecoder, JxlDecoderDestroyStruct> JxlDecoderPtr;
+
+/// Creates an instance of JxlDecoder into a JxlDecoderPtr and initializes it.
+///
+/// This function returns a unique_ptr that will call JxlDecoderDestroy() when
+/// releasing the pointer. See @ref JxlDecoderCreate for details on the
+/// instance creation.
+///
+/// @param memory_manager custom allocator function. It may be NULL. The memory
+/// manager will be copied internally.
+/// @return a @c NULL JxlDecoderPtr if the instance can not be allocated or
+/// initialized
+/// @return initialized JxlDecoderPtr instance otherwise.
+static inline JxlDecoderPtr JxlDecoderMake(
+ const JxlMemoryManager* memory_manager) {
+ return JxlDecoderPtr(JxlDecoderCreate(memory_manager));
+}
+
+#endif // JXL_DECODE_CXX_H_
+
+/// @}
diff --git a/third_party/jpeg-xl/lib/include/jxl/encode.h b/third_party/jpeg-xl/lib/include/jxl/encode.h
new file mode 100644
index 0000000000..2a87821f06
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/encode.h
@@ -0,0 +1,1580 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_encoder
+ * @{
+ * @file encode.h
+ * @brief Encoding API for JPEG XL.
+ */
+
+#ifndef JXL_ENCODE_H_
+#define JXL_ENCODE_H_
+
+#include <jxl/cms_interface.h>
+#include <jxl/codestream_header.h>
+#include <jxl/color_encoding.h>
+#include <jxl/jxl_export.h>
+#include <jxl/memory_manager.h>
+#include <jxl/parallel_runner.h>
+#include <jxl/stats.h>
+#include <jxl/types.h>
+#include <jxl/version.h> // TODO(eustas): remove before v1.0
+#include <stddef.h>
+#include <stdint.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/**
+ * Encoder library version.
+ *
+ * @return the encoder library version as an integer:
+ * MAJOR_VERSION * 1000000 + MINOR_VERSION * 1000 + PATCH_VERSION. For example,
+ * version 1.2.3 would return 1002003.
+ */
+JXL_EXPORT uint32_t JxlEncoderVersion(void);
+
+/**
+ * Opaque structure that holds the JPEG XL encoder.
+ *
+ * Allocated and initialized with JxlEncoderCreate().
+ * Cleaned up and deallocated with JxlEncoderDestroy().
+ */
+typedef struct JxlEncoderStruct JxlEncoder;
+
+/**
+ * Settings and metadata for a single image frame. This includes encoder options
+ * for a frame such as compression quality and speed.
+ *
+ * Allocated and initialized with JxlEncoderFrameSettingsCreate().
+ * Cleaned up and deallocated when the encoder is destroyed with
+ * JxlEncoderDestroy().
+ */
+typedef struct JxlEncoderFrameSettingsStruct JxlEncoderFrameSettings;
+
+/**
+ * Return value for multiple encoder functions.
+ */
+typedef enum {
+ /** Function call finished successfully, or encoding is finished and there is
+ * nothing more to be done.
+ */
+ JXL_ENC_SUCCESS = 0,
+
+ /** An error occurred, for example out of memory.
+ */
+ JXL_ENC_ERROR = 1,
+
+ /** The encoder needs more output buffer to continue encoding.
+ */
+ JXL_ENC_NEED_MORE_OUTPUT = 2,
+
+} JxlEncoderStatus;
+
+/**
+ * Error conditions:
+ * API usage errors have the 0x80 bit set to 1
+ * Other errors have the 0x80 bit set to 0
+ */
+typedef enum {
+ /** No error
+ */
+ JXL_ENC_ERR_OK = 0,
+
+ /** Generic encoder error due to unspecified cause
+ */
+ JXL_ENC_ERR_GENERIC = 1,
+
+ /** Out of memory
+ * TODO(jon): actually catch this and return this error
+ */
+ JXL_ENC_ERR_OOM = 2,
+
+ /** JPEG bitstream reconstruction data could not be
+ * represented (e.g. too much tail data)
+ */
+ JXL_ENC_ERR_JBRD = 3,
+
+ /** Input is invalid (e.g. corrupt JPEG file or ICC profile)
+ */
+ JXL_ENC_ERR_BAD_INPUT = 4,
+
+ /** The encoder doesn't (yet) support this. Either no version of libjxl
+ * supports this, and the API is used incorrectly, or the libjxl version
+ * should have been checked before trying to do this.
+ */
+ JXL_ENC_ERR_NOT_SUPPORTED = 0x80,
+
+ /** The encoder API is used in an incorrect way.
+ * In this case, a debug build of libjxl should output a specific error
+ * message. (if not, please open an issue about it)
+ */
+ JXL_ENC_ERR_API_USAGE = 0x81,
+
+} JxlEncoderError;
+
+/**
+ * Id of encoder options for a frame. This includes options such as setting
+ * encoding effort/speed or overriding the use of certain coding tools, for this
+ * frame. This does not include non-frame related encoder options such as for
+ * boxes.
+ */
+typedef enum {
+ /** Sets encoder effort/speed level without affecting decoding speed. Valid
+ * values are, from faster to slower speed: 1:lightning 2:thunder 3:falcon
+ * 4:cheetah 5:hare 6:wombat 7:squirrel 8:kitten 9:tortoise.
+ * Default: squirrel (7).
+ */
+ JXL_ENC_FRAME_SETTING_EFFORT = 0,
+
+ /** Sets the decoding speed tier for the provided options. Minimum is 0
+ * (slowest to decode, best quality/density), and maximum is 4 (fastest to
+ * decode, at the cost of some quality/density). Default is 0.
+ */
+ JXL_ENC_FRAME_SETTING_DECODING_SPEED = 1,
+
+ /** Sets resampling option. If enabled, the image is downsampled before
+ * compression, and upsampled to original size in the decoder. Integer option,
+ * use -1 for the default behavior (resampling only applied for low quality),
+ * 1 for no downsampling (1x1), 2 for 2x2 downsampling, 4 for 4x4
+ * downsampling, 8 for 8x8 downsampling.
+ */
+ JXL_ENC_FRAME_SETTING_RESAMPLING = 2,
+
+ /** Similar to JXL_ENC_FRAME_SETTING_RESAMPLING, but for extra channels.
+ * Integer option, use -1 for the default behavior (depends on encoder
+ * implementation), 1 for no downsampling (1x1), 2 for 2x2 downsampling, 4 for
+ * 4x4 downsampling, 8 for 8x8 downsampling.
+ */
+ JXL_ENC_FRAME_SETTING_EXTRA_CHANNEL_RESAMPLING = 3,
+
+ /** Indicates the frame added with @ref JxlEncoderAddImageFrame is already
+ * downsampled by the downsampling factor set with @ref
+ * JXL_ENC_FRAME_SETTING_RESAMPLING. The input frame must then be given in the
+ * downsampled resolution, not the full image resolution. The downsampled
+ * resolution is given by ceil(xsize / resampling), ceil(ysize / resampling)
+ * with xsize and ysize the dimensions given in the basic info, and resampling
+ * the factor set with @ref JXL_ENC_FRAME_SETTING_RESAMPLING.
+ * Use 0 to disable, 1 to enable. Default value is 0.
+ */
+ JXL_ENC_FRAME_SETTING_ALREADY_DOWNSAMPLED = 4,
+
+ /** Adds noise to the image emulating photographic film noise, the higher the
+ * given number, the grainier the image will be. As an example, a value of 100
+ * gives low noise whereas a value of 3200 gives a lot of noise. The default
+ * value is 0.
+ */
+ JXL_ENC_FRAME_SETTING_PHOTON_NOISE = 5,
+
+ /** Enables adaptive noise generation. This setting is not recommended for
+ * use, please use JXL_ENC_FRAME_SETTING_PHOTON_NOISE instead. Use -1 for the
+ * default (encoder chooses), 0 to disable, 1 to enable.
+ */
+ JXL_ENC_FRAME_SETTING_NOISE = 6,
+
+ /** Enables or disables dots generation. Use -1 for the default (encoder
+ * chooses), 0 to disable, 1 to enable.
+ */
+ JXL_ENC_FRAME_SETTING_DOTS = 7,
+
+ /** Enables or disables patches generation. Use -1 for the default (encoder
+ * chooses), 0 to disable, 1 to enable.
+ */
+ JXL_ENC_FRAME_SETTING_PATCHES = 8,
+
+ /** Edge preserving filter level, -1 to 3. Use -1 for the default (encoder
+ * chooses), 0 to 3 to set a strength.
+ */
+ JXL_ENC_FRAME_SETTING_EPF = 9,
+
+ /** Enables or disables the gaborish filter. Use -1 for the default (encoder
+ * chooses), 0 to disable, 1 to enable.
+ */
+ JXL_ENC_FRAME_SETTING_GABORISH = 10,
+
+ /** Enables modular encoding. Use -1 for default (encoder
+ * chooses), 0 to enforce VarDCT mode (e.g. for photographic images), 1 to
+ * enforce modular mode (e.g. for lossless images).
+ */
+ JXL_ENC_FRAME_SETTING_MODULAR = 11,
+
+ /** Enables or disables preserving color of invisible pixels. Use -1 for the
+ * default (1 if lossless, 0 if lossy), 0 to disable, 1 to enable.
+ */
+ JXL_ENC_FRAME_SETTING_KEEP_INVISIBLE = 12,
+
+ /** Determines the order in which 256x256 regions are stored in the codestream
+ * for progressive rendering. Use -1 for the encoder
+ * default, 0 for scanline order, 1 for center-first order.
+ */
+ JXL_ENC_FRAME_SETTING_GROUP_ORDER = 13,
+
+ /** Determines the horizontal position of center for the center-first group
+ * order. Use -1 to automatically use the middle of the image, 0..xsize to
+ * specifically set it.
+ */
+ JXL_ENC_FRAME_SETTING_GROUP_ORDER_CENTER_X = 14,
+
+ /** Determines the center for the center-first group order. Use -1 to
+ * automatically use the middle of the image, 0..ysize to specifically set it.
+ */
+ JXL_ENC_FRAME_SETTING_GROUP_ORDER_CENTER_Y = 15,
+
+ /** Enables or disables progressive encoding for modular mode. Use -1 for the
+ * encoder default, 0 to disable, 1 to enable.
+ */
+ JXL_ENC_FRAME_SETTING_RESPONSIVE = 16,
+
+ /** Set the progressive mode for the AC coefficients of VarDCT, using spectral
+ * progression from the DCT coefficients. Use -1 for the encoder default, 0 to
+ * disable, 1 to enable.
+ */
+ JXL_ENC_FRAME_SETTING_PROGRESSIVE_AC = 17,
+
+ /** Set the progressive mode for the AC coefficients of VarDCT, using
+ * quantization of the least significant bits. Use -1 for the encoder default,
+ * 0 to disable, 1 to enable.
+ */
+ JXL_ENC_FRAME_SETTING_QPROGRESSIVE_AC = 18,
+
+ /** Set the progressive mode using lower-resolution DC images for VarDCT. Use
+ * -1 for the encoder default, 0 to disable, 1 to have an extra 64x64 lower
+ * resolution pass, 2 to have a 512x512 and 64x64 lower resolution pass.
+ */
+ JXL_ENC_FRAME_SETTING_PROGRESSIVE_DC = 19,
+
+ /** Use Global channel palette if the amount of colors is smaller than this
+ * percentage of range. Use 0-100 to set an explicit percentage, -1 to use the
+ * encoder default. Used for modular encoding.
+ */
+ JXL_ENC_FRAME_SETTING_CHANNEL_COLORS_GLOBAL_PERCENT = 20,
+
+ /** Use Local (per-group) channel palette if the amount of colors is smaller
+ * than this percentage of range. Use 0-100 to set an explicit percentage, -1
+ * to use the encoder default. Used for modular encoding.
+ */
+ JXL_ENC_FRAME_SETTING_CHANNEL_COLORS_GROUP_PERCENT = 21,
+
+ /** Use color palette if amount of colors is smaller than or equal to this
+ * amount, or -1 to use the encoder default. Used for modular encoding.
+ */
+ JXL_ENC_FRAME_SETTING_PALETTE_COLORS = 22,
+
+ /** Enables or disables delta palette. Use -1 for the default (encoder
+ * chooses), 0 to disable, 1 to enable. Used in modular mode.
+ */
+ JXL_ENC_FRAME_SETTING_LOSSY_PALETTE = 23,
+
+ /** Color transform for internal encoding: -1 = default, 0=XYB, 1=none (RGB),
+ * 2=YCbCr. The XYB setting performs the forward XYB transform. None and
+ * YCbCr both perform no transform, but YCbCr is used to indicate that the
+ * encoded data losslessly represents YCbCr values.
+ */
+ JXL_ENC_FRAME_SETTING_COLOR_TRANSFORM = 24,
+
+ /** Reversible color transform for modular encoding: -1=default, 0-41=RCT
+ * index, e.g. index 0 = none, index 6 = YCoCg.
+ * If this option is set to a non-default value, the RCT will be globally
+ * applied to the whole frame.
+ * The default behavior is to try several RCTs locally per modular group,
+ * depending on the speed and distance setting.
+ */
+ JXL_ENC_FRAME_SETTING_MODULAR_COLOR_SPACE = 25,
+
+ /** Group size for modular encoding: -1=default, 0=128, 1=256, 2=512, 3=1024.
+ */
+ JXL_ENC_FRAME_SETTING_MODULAR_GROUP_SIZE = 26,
+
+ /** Predictor for modular encoding. -1 = default, 0=zero, 1=left, 2=top,
+ * 3=avg0, 4=select, 5=gradient, 6=weighted, 7=topright, 8=topleft,
+ * 9=leftleft, 10=avg1, 11=avg2, 12=avg3, 13=toptop predictive average 14=mix
+ * 5 and 6, 15=mix everything.
+ */
+ JXL_ENC_FRAME_SETTING_MODULAR_PREDICTOR = 27,
+
+ /** Fraction of pixels used to learn MA trees as a percentage. -1 = default,
+ * 0 = no MA and fast decode, 50 = default value, 100 = all, values above
+ * 100 are also permitted. Higher values use more encoder memory.
+ */
+ JXL_ENC_FRAME_SETTING_MODULAR_MA_TREE_LEARNING_PERCENT = 28,
+
+ /** Number of extra (previous-channel) MA tree properties to use. -1 =
+ * default, 0-11 = valid values. Recommended values are in the range 0 to 3,
+ * or 0 to amount of channels minus 1 (including all extra channels, and
+ * excluding color channels when using VarDCT mode). Higher value gives slower
+ * encoding and slower decoding.
+ */
+ JXL_ENC_FRAME_SETTING_MODULAR_NB_PREV_CHANNELS = 29,
+
+ /** Enable or disable CFL (chroma-from-luma) for lossless JPEG recompression.
+ * -1 = default, 0 = disable CFL, 1 = enable CFL.
+ */
+ JXL_ENC_FRAME_SETTING_JPEG_RECON_CFL = 30,
+
+ /** Prepare the frame for indexing in the frame index box.
+ * 0 = ignore this frame (same as not setting a value),
+ * 1 = index this frame within the Frame Index Box.
+ * If any frames are indexed, the first frame needs to
+ * be indexed, too. If the first frame is not indexed, and
+ * a later frame is attempted to be indexed, JXL_ENC_ERROR will occur.
+ * If non-keyframes, i.e., frames with cropping, blending or patches are
+ * attempted to be indexed, JXL_ENC_ERROR will occur.
+ */
+ JXL_ENC_FRAME_INDEX_BOX = 31,
+
+ /** Sets brotli encode effort for use in JPEG recompression and compressed
+ * metadata boxes (brob). Can be -1 (default) or 0 (fastest) to 11 (slowest).
+ * Default is based on the general encode effort in case of JPEG
+ * recompression, and 4 for brob boxes.
+ */
+ JXL_ENC_FRAME_SETTING_BROTLI_EFFORT = 32,
+
+ /** Enables or disables brotli compression of metadata boxes derived from
+ * a JPEG frame when using JxlEncoderAddJPEGFrame. This has no effect on boxes
+ * added using JxlEncoderAddBox.
+ * -1 = default, 0 = disable compression, 1 = enable compression.
+ */
+ JXL_ENC_FRAME_SETTING_JPEG_COMPRESS_BOXES = 33,
+
+ /** Control what kind of buffering is used, when using chunked image frames.
+ * 0 = buffers everything, basically the same as non-streamed code path
+ (mainly for testing)
+ * 1 = buffers everything for images that are smaller than 2048 x 2048, and
+ * uses streaming input and output for larger images
+ * 2 = uses streaming input and output for all images that are larger than
+ * one group, i.e. 256 x 256 pixels by default
+ * 3 = currently same as 2
+ *
+ * When using streaming input and output the encoder minimizes memory usage at
+ * the cost of compression density. Also note that images produced with
+ * streaming mode might can not be decoded progressively.
+ */
+ JXL_ENC_FRAME_SETTING_BUFFERING = 34,
+
+ /** Keep or discard Exif metadata boxes derived from a JPEG frame when using
+ * JxlEncoderAddJPEGFrame. This has no effect on boxes added using
+ * JxlEncoderAddBox. When JxlEncoderStoreJPEGMetadata is set to 1, this option
+ * cannot be set to 0. Even when Exif metadata is discarded, the orientation
+ * will still be applied. 0 = discard Exif metadata, 1 = keep Exif metadata
+ * (default).
+ */
+ JXL_ENC_FRAME_SETTING_JPEG_KEEP_EXIF = 35,
+
+ /** Keep or discard XMP metadata boxes derived from a JPEG frame when using
+ * JxlEncoderAddJPEGFrame. This has no effect on boxes added using
+ * JxlEncoderAddBox. When JxlEncoderStoreJPEGMetadata is set to 1, this option
+ * cannot be set to 0. 0 = discard XMP metadata, 1 = keep XMP metadata
+ * (default).
+ */
+ JXL_ENC_FRAME_SETTING_JPEG_KEEP_XMP = 36,
+
+ /** Keep or discard JUMBF metadata boxes derived from a JPEG frame when using
+ * JxlEncoderAddJPEGFrame. This has no effect on boxes added using
+ * JxlEncoderAddBox. 0 = discard JUMBF metadata, 1 = keep JUMBF metadata
+ * (default).
+ */
+ JXL_ENC_FRAME_SETTING_JPEG_KEEP_JUMBF = 37,
+
+ /** If this mode is disabled, the encoder will not make any image quality
+ * decisions that are computed based on the full image, but stored only once
+ * (e.g. the X quant multiplier in the frame header). Used mainly for testing
+ * equivalence of streaming and non-streaming code.
+ * 0 = disabled, 1 = enabled (default)
+ */
+ JXL_ENC_FRAME_SETTING_USE_FULL_IMAGE_HEURISTICS = 38,
+
+ /** Enum value not to be used as an option. This value is added to force the
+ * C compiler to have the enum to take a known size.
+ */
+ JXL_ENC_FRAME_SETTING_FILL_ENUM = 65535,
+
+} JxlEncoderFrameSettingId;
+
+/**
+ * Creates an instance of JxlEncoder and initializes it.
+ *
+ * @p memory_manager will be used for all the library dynamic allocations made
+ * from this instance. The parameter may be NULL, in which case the default
+ * allocator will be used. See jpegxl/memory_manager.h for details.
+ *
+ * @param memory_manager custom allocator function. It may be NULL. The memory
+ * manager will be copied internally.
+ * @return @c NULL if the instance can not be allocated or initialized
+ * @return pointer to initialized JxlEncoder otherwise
+ */
+JXL_EXPORT JxlEncoder* JxlEncoderCreate(const JxlMemoryManager* memory_manager);
+
+/**
+ * Re-initializes a JxlEncoder instance, so it can be re-used for encoding
+ * another image. All state and settings are reset as if the object was
+ * newly created with JxlEncoderCreate, but the memory manager is kept.
+ *
+ * @param enc instance to be re-initialized.
+ */
+JXL_EXPORT void JxlEncoderReset(JxlEncoder* enc);
+
+/**
+ * Deinitializes and frees JxlEncoder instance.
+ *
+ * @param enc instance to be cleaned up and deallocated.
+ */
+JXL_EXPORT void JxlEncoderDestroy(JxlEncoder* enc);
+
+/**
+ * Sets the color management system (CMS) that will be used for color conversion
+ * (if applicable) during encoding. May only be set before starting encoding. If
+ * left unset, the default CMS implementation will be used.
+ *
+ * @param enc encoder object.
+ * @param cms structure representing a CMS implementation. See JxlCmsInterface
+ * for more details.
+ */
+JXL_EXPORT void JxlEncoderSetCms(JxlEncoder* enc, JxlCmsInterface cms);
+
+/**
+ * Set the parallel runner for multithreading. May only be set before starting
+ * encoding.
+ *
+ * @param enc encoder object.
+ * @param parallel_runner function pointer to runner for multithreading. It may
+ * be NULL to use the default, single-threaded, runner. A multithreaded
+ * runner should be set to reach fast performance.
+ * @param parallel_runner_opaque opaque pointer for parallel_runner.
+ * @return JXL_ENC_SUCCESS if the runner was set, JXL_ENC_ERROR
+ * otherwise (the previous runner remains set).
+ */
+JXL_EXPORT JxlEncoderStatus
+JxlEncoderSetParallelRunner(JxlEncoder* enc, JxlParallelRunner parallel_runner,
+ void* parallel_runner_opaque);
+
+/**
+ * Get the (last) error code in case JXL_ENC_ERROR was returned.
+ *
+ * @param enc encoder object.
+ * @return the JxlEncoderError that caused the (last) JXL_ENC_ERROR to be
+ * returned.
+ */
+JXL_EXPORT JxlEncoderError JxlEncoderGetError(JxlEncoder* enc);
+
+/**
+ * Encodes JPEG XL file using the available bytes. @p *avail_out indicates how
+ * many output bytes are available, and @p *next_out points to the input bytes.
+ * *avail_out will be decremented by the amount of bytes that have been
+ * processed by the encoder and *next_out will be incremented by the same
+ * amount, so *next_out will now point at the amount of *avail_out unprocessed
+ * bytes.
+ *
+ * The returned status indicates whether the encoder needs more output bytes.
+ * When the return value is not JXL_ENC_ERROR or JXL_ENC_SUCCESS, the encoding
+ * requires more JxlEncoderProcessOutput calls to continue.
+ *
+ * The caller must guarantee that *avail_out >= 32 when calling
+ * JxlEncoderProcessOutput; otherwise, JXL_ENC_NEED_MORE_OUTPUT will be
+ * returned. It is guaranteed that, if *avail_out >= 32, at least one byte of
+ * output will be written.
+ *
+ * This encodes the frames and/or boxes added so far. If the last frame or last
+ * box has been added, @ref JxlEncoderCloseInput, @ref JxlEncoderCloseFrames
+ * and/or @ref JxlEncoderCloseBoxes must be called before the next
+ * @ref JxlEncoderProcessOutput call, or the codestream won't be encoded
+ * correctly.
+ *
+ * @param enc encoder object.
+ * @param next_out pointer to next bytes to write to.
+ * @param avail_out amount of bytes available starting from *next_out.
+ * @return JXL_ENC_SUCCESS when encoding finished and all events handled.
+ * @return JXL_ENC_ERROR when encoding failed, e.g. invalid input.
+ * @return JXL_ENC_NEED_MORE_OUTPUT more output buffer is necessary.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderProcessOutput(JxlEncoder* enc,
+ uint8_t** next_out,
+ size_t* avail_out);
+
+/**
+ * Sets the frame information for this frame to the encoder. This includes
+ * animation information such as frame duration to store in the frame header.
+ * The frame header fields represent the frame as passed to the encoder, but not
+ * necessarily the exact values as they will be encoded file format: the encoder
+ * could change crop and blending options of a frame for more efficient encoding
+ * or introduce additional internal frames. Animation duration and time code
+ * information is not altered since those are immutable metadata of the frame.
+ *
+ * It is not required to use this function, however if have_animation is set
+ * to true in the basic info, then this function should be used to set the
+ * time duration of this individual frame. By default individual frames have a
+ * time duration of 0, making them form a composite still. See @ref
+ * JxlFrameHeader for more information.
+ *
+ * This information is stored in the JxlEncoderFrameSettings and so is used for
+ * any frame encoded with these JxlEncoderFrameSettings. It is ok to change
+ * between @ref JxlEncoderAddImageFrame calls, each added image frame will have
+ * the frame header that was set in the options at the time of calling
+ * JxlEncoderAddImageFrame.
+ *
+ * The is_last and name_length fields of the JxlFrameHeader are ignored, use
+ * @ref JxlEncoderCloseFrames to indicate last frame, and @ref
+ * JxlEncoderSetFrameName to indicate the name and its length instead.
+ * Calling this function will clear any name that was previously set with @ref
+ * JxlEncoderSetFrameName.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param frame_header frame header data to set. Object owned by the caller and
+ * does not need to be kept in memory, its information is copied internally.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ */
+JXL_EXPORT JxlEncoderStatus
+JxlEncoderSetFrameHeader(JxlEncoderFrameSettings* frame_settings,
+ const JxlFrameHeader* frame_header);
+
+/**
+ * Sets blend info of an extra channel. The blend info of extra channels is set
+ * separately from that of the color channels, the color channels are set with
+ * @ref JxlEncoderSetFrameHeader.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param index index of the extra channel to use.
+ * @param blend_info blend info to set for the extra channel
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBlendInfo(
+ JxlEncoderFrameSettings* frame_settings, size_t index,
+ const JxlBlendInfo* blend_info);
+
+/**
+ * Sets the name of the animation frame. This function is optional, frames are
+ * not required to have a name. This setting is a part of the frame header, and
+ * the same principles as for @ref JxlEncoderSetFrameHeader apply. The
+ * name_length field of JxlFrameHeader is ignored by the encoder, this function
+ * determines the name length instead as the length in bytes of the C string.
+ *
+ * The maximum possible name length is 1071 bytes (excluding terminating null
+ * character).
+ *
+ * Calling @ref JxlEncoderSetFrameHeader clears any name that was
+ * previously set.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param frame_name name of the next frame to be encoded, as a UTF-8 encoded C
+ * string (zero terminated). Owned by the caller, and copied internally.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameName(
+ JxlEncoderFrameSettings* frame_settings, const char* frame_name);
+
+/**
+ * Sets the bit depth of the input buffer.
+ *
+ * For float pixel formats, only the default JXL_BIT_DEPTH_FROM_PIXEL_FORMAT
+ * setting is allowed, while for unsigned pixel formats,
+ * JXL_BIT_DEPTH_FROM_CODESTREAM setting is also allowed. See the comment on
+ * @ref JxlEncoderAddImageFrame for the effects of the bit depth setting.
+
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param bit_depth the bit depth setting of the pixel input
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameBitDepth(
+ JxlEncoderFrameSettings* frame_settings, const JxlBitDepth* bit_depth);
+
+/**
+ * Sets the buffer to read JPEG encoded bytes from for the next frame to encode.
+ *
+ * If JxlEncoderSetBasicInfo has not yet been called, calling
+ * JxlEncoderAddJPEGFrame will implicitly call it with the parameters of the
+ * added JPEG frame.
+ *
+ * If JxlEncoderSetColorEncoding or JxlEncoderSetICCProfile has not yet been
+ * called, calling JxlEncoderAddJPEGFrame will implicitly call it with the
+ * parameters of the added JPEG frame.
+ *
+ * If the encoder is set to store JPEG reconstruction metadata using @ref
+ * JxlEncoderStoreJPEGMetadata and a single JPEG frame is added, it will be
+ * possible to losslessly reconstruct the JPEG codestream.
+ *
+ * If this is the last frame, @ref JxlEncoderCloseInput or @ref
+ * JxlEncoderCloseFrames must be called before the next
+ * @ref JxlEncoderProcessOutput call.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param buffer bytes to read JPEG from. Owned by the caller and its contents
+ * are copied internally.
+ * @param size size of buffer in bytes.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ */
+JXL_EXPORT JxlEncoderStatus
+JxlEncoderAddJPEGFrame(const JxlEncoderFrameSettings* frame_settings,
+ const uint8_t* buffer, size_t size);
+
+/**
+ * Sets the buffer to read pixels from for the next image to encode. Must call
+ * JxlEncoderSetBasicInfo before JxlEncoderAddImageFrame.
+ *
+ * Currently only some data types for pixel formats are supported:
+ * - JXL_TYPE_UINT8, with range 0..255
+ * - JXL_TYPE_UINT16, with range 0..65535
+ * - JXL_TYPE_FLOAT16, with nominal range 0..1
+ * - JXL_TYPE_FLOAT, with nominal range 0..1
+ *
+ * Note: the sample data type in pixel_format is allowed to be different from
+ * what is described in the JxlBasicInfo. The type in pixel_format, together
+ * with an optional @ref JxlBitDepth parameter set by @ref
+ * JxlEncoderSetFrameBitDepth describes the format of the uncompressed pixel
+ * buffer. The bits_per_sample and exponent_bits_per_sample in the JxlBasicInfo
+ * describes what will actually be encoded in the JPEG XL codestream.
+ * For example, to encode a 12-bit image, you would set bits_per_sample to 12,
+ * while the input frame buffer can be in the following formats:
+ * - if pixel format is in JXL_TYPE_UINT16 with default bit depth setting
+ * (i.e. JXL_BIT_DEPTH_FROM_PIXEL_FORMAT), input sample values are rescaled
+ * to 16-bit, i.e. multiplied by 65535/4095;
+ * - if pixel format is in JXL_TYPE_UINT16 with JXL_BIT_DEPTH_FROM_CODESTREAM
+ * bit depth setting, input sample values are provided unscaled;
+ * - if pixel format is in JXL_TYPE_FLOAT, input sample values are rescaled
+ * to 0..1, i.e. multiplied by 1.f/4095.f.
+ * While it is allowed, it is obviously not recommended to use a pixel_format
+ * with lower precision than what is specified in the JxlBasicInfo.
+ *
+ * We support interleaved channels as described by the JxlPixelFormat:
+ * - single-channel data, e.g. grayscale
+ * - single-channel + alpha
+ * - trichromatic, e.g. RGB
+ * - trichromatic + alpha
+ *
+ * Extra channels not handled here need to be set by @ref
+ * JxlEncoderSetExtraChannelBuffer.
+ * If the image has alpha, and alpha is not passed here, it will implicitly be
+ * set to all-opaque (an alpha value of 1.0 everywhere).
+ *
+ * The pixels are assumed to be encoded in the original profile that is set with
+ * JxlEncoderSetColorEncoding or JxlEncoderSetICCProfile. If none of these
+ * functions were used, the pixels are assumed to be nonlinear sRGB for integer
+ * data types (JXL_TYPE_UINT8, JXL_TYPE_UINT16), and linear sRGB for floating
+ * point data types (JXL_TYPE_FLOAT16, JXL_TYPE_FLOAT).
+ *
+ * Sample values in floating-point pixel formats are allowed to be outside the
+ * nominal range, e.g. to represent out-of-sRGB-gamut colors in the
+ * uses_original_profile=false case. They are however not allowed to be NaN or
+ * +-infinity.
+ *
+ * If this is the last frame, @ref JxlEncoderCloseInput or @ref
+ * JxlEncoderCloseFrames must be called before the next
+ * @ref JxlEncoderProcessOutput call.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param pixel_format format for pixels. Object owned by the caller and its
+ * contents are copied internally.
+ * @param buffer buffer type to input the pixel data from. Owned by the caller
+ * and its contents are copied internally.
+ * @param size size of buffer in bytes. This size should match what is implied
+ * by the frame dimensions and the pixel format.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderAddImageFrame(
+ const JxlEncoderFrameSettings* frame_settings,
+ const JxlPixelFormat* pixel_format, const void* buffer, size_t size);
+
+/**
+ * The JxlEncoderOutputProcessor structure provides an interface for the
+ * encoder's output processing. Users of the library, who want to do streaming
+ * encoding, should implement the required callbacks for buffering, writing,
+ * seeking (if supported), and setting a finalized position during the encoding
+ * process.
+ *
+ * At a high level, the processor can be in one of two states:
+ * - With an active buffer: This indicates that a buffer has been acquired using
+ * `get_buffer` and encoded data can be written to it.
+ * - Without an active buffer: In this state, no data can be written. A new
+ * buffer must be acquired after releasing any previously active buffer.
+ *
+ * The library will not acquire more than one buffer at a given time.
+ *
+ * The state of the processor includes `position` and `finalized position`,
+ * which have the following meaning.
+ *
+ * - position: Represents the current position, in bytes, within the output
+ * stream where the encoded data will be written next. This position moves
+ * forward with each `release_buffer` call as data is written, and can also be
+ * adjusted through the optional seek callback, if provided. At this position
+ * the next write will occur.
+ *
+ * - finalized position: A position in the output stream that ensures all bytes
+ * before this point are finalized and won't be changed by later writes.
+ *
+ * All fields but `seek` are required, `seek` is optional and can be NULL.
+ */
+struct JxlEncoderOutputProcessor {
+ /**
+ * Required.
+ * An opaque pointer that the client can use to store custom data.
+ * This data will be passed to the associated callback functions.
+ */
+ void* opaque;
+
+ /**
+ * Required.
+ * Acquires a buffer at the current position into which the library will write
+ * the output data.
+ *
+ * If the `size` argument points to 0 and the returned value is NULL, this
+ * will be interpreted as asking the output writing to stop. In such a case,
+ * the library will return an error. The client is expected to set the size of
+ * the returned buffer based on the suggested `size` when this function is
+ * called.
+ *
+ * @param opaque user supplied parameters to the callback
+ * @param size points to a suggested buffer size when called; must be set to
+ * the size of the returned buffer once the function returns.
+ * @return a pointer to the acquired buffer or NULL to indicate a stop
+ * condition.
+ */
+ void* (*get_buffer)(void* opaque, size_t* size);
+
+ /**
+ * Required.
+ * Notifies the user of library that the current buffer's data has been
+ * written and can be released. This function should advance the current
+ * position of the buffer by `written_bytes` number of bytes.
+ *
+ * @param opaque user supplied parameters to the callback
+ * @param written_bytes the number of bytes written to the buffer.
+ */
+ void (*release_buffer)(void* opaque, size_t written_bytes);
+
+ /**
+ * Optional, can be NULL
+ * Seeks to a specific position in the output. This function is optional and
+ * can be set to NULL if the output doesn't support seeking. Can only be done
+ * when there is no buffer. Cannot be used to seek before the finalized
+ * position.
+ *
+ * @param opaque user supplied parameters to the callback
+ * @param position the position to seek to, in bytes.
+ */
+ void (*seek)(void* opaque, uint64_t position);
+
+ /**
+ * Required.
+ * Sets a finalized position on the output data, at a specific position.
+ * Seeking will never request a position before the finalized position.
+ *
+ * Will only be called if there is no active buffer.
+ *
+ * @param opaque user supplied parameters to the callback
+ * @param finalized_position the position, in bytes, where the finalized
+ * position should be set.
+ */
+ void (*set_finalized_position)(void* opaque, uint64_t finalized_position);
+};
+
+/**
+ * Sets the output processor for the encoder. This processor determines how the
+ * encoder will handle buffering, writing, seeking (if supported), and
+ * setting a finalized position during the encoding process.
+ *
+ * This should not be used when using @ref JxlEncoderProcessOutput.
+ *
+ * @param enc encoder object.
+ * @param output_processor the struct containing the callbacks for managing
+ * output.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetOutputProcessor(
+ JxlEncoder* enc, struct JxlEncoderOutputProcessor output_processor);
+
+/**
+ * Flushes any buffered input in the encoder, ensuring that all available input
+ * data has been processed and written to the output.
+ *
+ * This function can only be used after @ref JxlEncoderSetOutputProcessor.
+ * Before making the last call to @ref JxlEncoderFlushInput, users should call
+ * @ref JxlEncoderCloseInput to signal the end of input data.
+ *
+ * This should not be used when using @ref JxlEncoderProcessOutput.
+ *
+ * @param enc encoder object.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderFlushInput(JxlEncoder* enc);
+
+/**
+ * This struct provides callback functions to pass pixel data in a streaming
+ * manner instead of requiring the entire frame data in memory at once.
+ */
+struct JxlChunkedFrameInputSource {
+ /**
+ * A pointer to any user-defined data or state. This can be used to pass
+ * information to the callback functions.
+ */
+ void* opaque;
+
+ /**
+ * Get the pixel format that color channel data will be provided in.
+ * When called, `pixel_format` points to a suggested pixel format; if
+ * color channel data can be given in this pixel format, processing might
+ * be more efficient.
+ *
+ * This function will be called exactly once, before any call to
+ * get_color_channel_at.
+ *
+ * @param opaque user supplied parameters to the callback
+ * @param pixel_format format for pixels
+ */
+ void (*get_color_channels_pixel_format)(void* opaque,
+ JxlPixelFormat* pixel_format);
+
+ /**
+ * Callback to retrieve a rectangle of color channel data at a specific
+ * location. It is guaranteed that xpos and ypos are multiples of 8. xsize,
+ * ysize will be multiples of 8, unless the resulting rectangle would be out
+ * of image bounds. Moreover, xsize and ysize will be at most 2048. The
+ * returned data will be assumed to be in the format returned by the
+ * (preceding) call to get_color_channels_pixel_format, except the `align`
+ * parameter of the pixel format will be ignored. Instead, the `i`-th row will
+ * be assumed to start at position `return_value + i * *row_offset`, with the
+ * value of `*row_offset` decided by the callee.
+ *
+ * Note that multiple calls to `get_color_channel_data_at` may happen before a
+ * call to `release_buffer`.
+ *
+ * @param opaque user supplied parameters to the callback
+ * @param xpos horizontal position for the data.
+ * @param ypos vertical position for the data.
+ * @param xsize horizontal size of the requested rectangle of data.
+ * @param ysize vertical size of the requested rectangle of data.
+ * @param row_offset pointer to a the byte offset between consecutive rows of
+ * the retrieved pixel data.
+ * @return pointer to the retrieved pixel data.
+ */
+ const void* (*get_color_channel_data_at)(void* opaque, size_t xpos,
+ size_t ypos, size_t xsize,
+ size_t ysize, size_t* row_offset);
+
+ /**
+ * Get the pixel format that extra channel data will be provided in.
+ * When called, `pixel_format` points to a suggested pixel format; if
+ * extra channel data can be given in this pixel format, processing might
+ * be more efficient.
+ *
+ * This function will be called exactly once per index, before any call to
+ * get_extra_channel_data_at with that given index.
+ *
+ * @param opaque user supplied parameters to the callback
+ * @param ec_index zero-indexed index of the extra channel
+ * @param pixel_format format for extra channel data
+ */
+ void (*get_extra_channel_pixel_format)(void* opaque, size_t ec_index,
+ JxlPixelFormat* pixel_format);
+
+ /**
+ * Callback to retrieve a rectangle of extra channel `ec_index` data at a
+ * specific location. It is guaranteed that xpos and ypos are multiples of
+ * 8. xsize, ysize will be multiples of 8, unless the resulting rectangle
+ * would be out of image bounds. Moreover, xsize and ysize will be at most
+ * 2048. The returned data will be assumed to be in the format returned by the
+ * (preceding) call to get_extra_channels_pixel_format_at with the
+ * corresponding extra channel index `ec_index`, except the `align` parameter
+ * of the pixel format will be ignored. Instead, the `i`-th row will be
+ * assumed to start at position `return_value + i * *row_offset`, with the
+ * value of `*row_offset` decided by the callee.
+ *
+ * Note that multiple calls to `get_extra_channel_data_at` may happen before a
+ * call to `release_buffer`.
+ *
+ * @param opaque user supplied parameters to the callback
+ * @param xpos horizontal position for the data.
+ * @param ypos vertical position for the data.
+ * @param xsize horizontal size of the requested rectangle of data.
+ * @param ysize vertical size of the requested rectangle of data.
+ * @param row_offset pointer to a the byte offset between consecutive rows of
+ * the retrieved pixel data.
+ * @return pointer to the retrieved pixel data.
+ */
+ const void* (*get_extra_channel_data_at)(void* opaque, size_t ec_index,
+ size_t xpos, size_t ypos,
+ size_t xsize, size_t ysize,
+ size_t* row_offset);
+
+ /**
+ * Releases the buffer `buf` (obtained through a call to
+ * `get_color_channel_data_at` or `get_extra_channel_data_at`). This function
+ * will be called exactly once per call to `get_color_channel_data_at` or
+ * `get_extra_channel_data_at`.
+ *
+ * @param opaque user supplied parameters to the callback
+ * @param buf pointer returned by `get_color_channel_data_at` or
+ * `get_extra_channel_data_at`
+ */
+ void (*release_buffer)(void* opaque, const void* buf);
+};
+
+/**
+ * @brief Adds a frame to the encoder using a chunked input source.
+ *
+ * This function gives a way to encode a frame by providing pixel data in a
+ * chunked or streaming manner, which can be especially useful when dealing with
+ * large images that may not fit entirely in memory or when trying to optimize
+ * memory usage. The input data is provided through callbacks defined in the
+ * `JxlChunkedFrameInputSource` struct. Once the frame data has been completely
+ * retrieved, this function will flush the input and close it if it is the last
+ * frame.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param is_last_frame indicates if this is the last frame.
+ * @param chunked_frame_input struct providing callback methods for retrieving
+ * pixel data in chunks.
+ *
+ * @return Returns a status indicating the success or failure of adding the
+ * frame.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderAddChunkedFrame(
+ const JxlEncoderFrameSettings* frame_settings, JXL_BOOL is_last_frame,
+ struct JxlChunkedFrameInputSource chunked_frame_input);
+
+/**
+ * Sets the buffer to read pixels from for an extra channel at a given index.
+ * The index must be smaller than the num_extra_channels in the associated
+ * JxlBasicInfo. Must call @ref JxlEncoderSetExtraChannelInfo before
+ * JxlEncoderSetExtraChannelBuffer.
+ *
+ * TODO(firsching): mention what data types in pixel formats are supported.
+ *
+ * It is required to call this function for every extra channel, except for the
+ * alpha channel if that was already set through @ref JxlEncoderAddImageFrame.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param pixel_format format for pixels. Object owned by the caller and its
+ * contents are copied internally. The num_channels value is ignored, since the
+ * number of channels for an extra channel is always assumed to be one.
+ * @param buffer buffer type to input the pixel data from. Owned by the caller
+ * and its contents are copied internally.
+ * @param size size of buffer in bytes. This size should match what is implied
+ * by the frame dimensions and the pixel format.
+ * @param index index of the extra channel to use.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBuffer(
+ const JxlEncoderFrameSettings* frame_settings,
+ const JxlPixelFormat* pixel_format, const void* buffer, size_t size,
+ uint32_t index);
+
+/** Adds a metadata box to the file format. JxlEncoderProcessOutput must be used
+ * to effectively write the box to the output. @ref JxlEncoderUseBoxes must
+ * be enabled before using this function.
+ *
+ * Boxes allow inserting application-specific data and metadata (Exif, XML/XMP,
+ * JUMBF and user defined boxes).
+ *
+ * The box format follows ISO BMFF and shares features and box types with other
+ * image and video formats, including the Exif, XML and JUMBF boxes. The box
+ * format for JPEG XL is specified in ISO/IEC 18181-2.
+ *
+ * Boxes in general don't contain other boxes inside, except a JUMBF superbox.
+ * Boxes follow each other sequentially and are byte-aligned. If the container
+ * format is used, the JXL stream consists of concatenated boxes.
+ * It is also possible to use a direct codestream without boxes, but in that
+ * case metadata cannot be added.
+ *
+ * Each box generally has the following byte structure in the file:
+ * - 4 bytes: box size including box header (Big endian. If set to 0, an
+ * 8-byte 64-bit size follows instead).
+ * - 4 bytes: type, e.g. "JXL " for the signature box, "jxlc" for a codestream
+ * box.
+ * - N bytes: box contents.
+ *
+ * Only the box contents are provided to the contents argument of this function,
+ * the encoder encodes the size header itself. Most boxes are written
+ * automatically by the encoder as needed ("JXL ", "ftyp", "jxll", "jxlc",
+ * "jxlp", "jxli", "jbrd"), and this function only needs to be called to add
+ * optional metadata when encoding from pixels (using JxlEncoderAddImageFrame).
+ * When recompressing JPEG files (using JxlEncoderAddJPEGFrame), if the input
+ * JPEG contains EXIF, XMP or JUMBF metadata, the corresponding boxes are
+ * already added automatically.
+ *
+ * Box types are given by 4 characters. The following boxes can be added with
+ * this function:
+ * - "Exif": a box with EXIF metadata, can be added by libjxl users, or is
+ * automatically added when needed for JPEG reconstruction. The contents of
+ * this box must be prepended by a 4-byte tiff header offset, which may
+ * be 4 zero bytes in case the tiff header follows immediately.
+ * The EXIF metadata must be in sync with what is encoded in the JPEG XL
+ * codestream, specifically the image orientation. While this is not
+ * recommended in practice, in case of conflicting metadata, the JPEG XL
+ * codestream takes precedence.
+ * - "xml ": a box with XML data, in particular XMP metadata, can be added by
+ * libjxl users, or is automatically added when needed for JPEG reconstruction
+ * - "jumb": a JUMBF superbox, which can contain boxes with different types of
+ * metadata inside. This box type can be added by the encoder transparently,
+ * and other libraries to create and handle JUMBF content exist.
+ * - Application-specific boxes. Their typename should not begin with "jxl" or
+ * "JXL" or conflict with other existing typenames, and they should be
+ * registered with MP4RA (mp4ra.org).
+ *
+ * These boxes can be stored uncompressed or Brotli-compressed (using a "brob"
+ * box), depending on the compress_box parameter.
+ *
+ * @param enc encoder object.
+ * @param type the box type, e.g. "Exif" for EXIF metadata, "xml " for XMP or
+ * IPTC metadata, "jumb" for JUMBF metadata.
+ * @param contents the full contents of the box, for example EXIF
+ * data. ISO BMFF box header must not be included, only the contents. Owned by
+ * the caller and its contents are copied internally.
+ * @param size size of the box contents.
+ * @param compress_box Whether to compress this box as a "brob" box. Requires
+ * Brotli support.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error, such as when
+ * using this function without JxlEncoderUseContainer, or adding a box type
+ * that would result in an invalid file format.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderAddBox(JxlEncoder* enc,
+ const JxlBoxType type,
+ const uint8_t* contents,
+ size_t size,
+ JXL_BOOL compress_box);
+
+/**
+ * Indicates the intention to add metadata boxes. This allows @ref
+ * JxlEncoderAddBox to be used. When using this function, then it is required
+ * to use @ref JxlEncoderCloseBoxes at the end.
+ *
+ * By default the encoder assumes no metadata boxes will be added.
+ *
+ * This setting can only be set at the beginning, before encoding starts.
+ *
+ * @param enc encoder object.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderUseBoxes(JxlEncoder* enc);
+
+/**
+ * Declares that no further boxes will be added with @ref JxlEncoderAddBox.
+ * This function must be called after the last box is added so the encoder knows
+ * the stream will be finished. It is not necessary to use this function if
+ * @ref JxlEncoderUseBoxes is not used. Further frames may still be added.
+ *
+ * Must be called between JxlEncoderAddBox of the last box
+ * and the next call to JxlEncoderProcessOutput, or @ref JxlEncoderProcessOutput
+ * won't output the last box correctly.
+ *
+ * NOTE: if you don't need to close frames and boxes at separate times, you can
+ * use @ref JxlEncoderCloseInput instead to close both at once.
+ *
+ * @param enc encoder object.
+ */
+JXL_EXPORT void JxlEncoderCloseBoxes(JxlEncoder* enc);
+
+/**
+ * Declares that no frames will be added and @ref JxlEncoderAddImageFrame and
+ * @ref JxlEncoderAddJPEGFrame won't be called anymore. Further metadata boxes
+ * may still be added. This function or @ref JxlEncoderCloseInput must be called
+ * after adding the last frame and the next call to
+ * @ref JxlEncoderProcessOutput, or the frame won't be properly marked as last.
+ *
+ * NOTE: if you don't need to close frames and boxes at separate times, you can
+ * use @ref JxlEncoderCloseInput instead to close both at once.
+ *
+ * @param enc encoder object.
+ */
+JXL_EXPORT void JxlEncoderCloseFrames(JxlEncoder* enc);
+
+/**
+ * Closes any input to the encoder, equivalent to calling JxlEncoderCloseFrames
+ * as well as calling JxlEncoderCloseBoxes if needed. No further input of any
+ * kind may be given to the encoder, but further @ref JxlEncoderProcessOutput
+ * calls should be done to create the final output.
+ *
+ * The requirements of both @ref JxlEncoderCloseFrames and @ref
+ * JxlEncoderCloseBoxes apply to this function. Either this function or the
+ * other two must be called after the final frame and/or box, and the next
+ * @ref JxlEncoderProcessOutput call, or the codestream won't be encoded
+ * correctly.
+ *
+ * @param enc encoder object.
+ */
+JXL_EXPORT void JxlEncoderCloseInput(JxlEncoder* enc);
+
+/**
+ * Sets the original color encoding of the image encoded by this encoder. This
+ * is an alternative to JxlEncoderSetICCProfile and only one of these two must
+ * be used. This one sets the color encoding as a @ref JxlColorEncoding, while
+ * the other sets it as ICC binary data.
+ * Must be called after JxlEncoderSetBasicInfo.
+ *
+ * @param enc encoder object.
+ * @param color color encoding. Object owned by the caller and its contents are
+ * copied internally.
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR or
+ * JXL_ENC_NOT_SUPPORTED otherwise
+ */
+JXL_EXPORT JxlEncoderStatus
+JxlEncoderSetColorEncoding(JxlEncoder* enc, const JxlColorEncoding* color);
+
+/**
+ * Sets the original color encoding of the image encoded by this encoder as an
+ * ICC color profile. This is an alternative to JxlEncoderSetColorEncoding and
+ * only one of these two must be used. This one sets the color encoding as ICC
+ * binary data, while the other defines it as a @ref JxlColorEncoding.
+ * Must be called after JxlEncoderSetBasicInfo.
+ *
+ * @param enc encoder object.
+ * @param icc_profile bytes of the original ICC profile
+ * @param size size of the icc_profile buffer in bytes
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR or
+ * JXL_ENC_NOT_SUPPORTED otherwise
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetICCProfile(JxlEncoder* enc,
+ const uint8_t* icc_profile,
+ size_t size);
+
+/**
+ * Initializes a JxlBasicInfo struct to default values.
+ * For forwards-compatibility, this function has to be called before values
+ * are assigned to the struct fields.
+ * The default values correspond to an 8-bit RGB image, no alpha or any
+ * other extra channels.
+ *
+ * @param info global image metadata. Object owned by the caller.
+ */
+JXL_EXPORT void JxlEncoderInitBasicInfo(JxlBasicInfo* info);
+
+/**
+ * Initializes a JxlFrameHeader struct to default values.
+ * For forwards-compatibility, this function has to be called before values
+ * are assigned to the struct fields.
+ * The default values correspond to a frame with no animation duration and the
+ * 'replace' blend mode. After using this function, For animation duration must
+ * be set, for composite still blend settings must be set.
+ *
+ * @param frame_header frame metadata. Object owned by the caller.
+ */
+JXL_EXPORT void JxlEncoderInitFrameHeader(JxlFrameHeader* frame_header);
+
+/**
+ * Initializes a JxlBlendInfo struct to default values.
+ * For forwards-compatibility, this function has to be called before values
+ * are assigned to the struct fields.
+ *
+ * @param blend_info blending info. Object owned by the caller.
+ */
+JXL_EXPORT void JxlEncoderInitBlendInfo(JxlBlendInfo* blend_info);
+
+/**
+ * Sets the global metadata of the image encoded by this encoder.
+ *
+ * If the JxlBasicInfo contains information of extra channels beyond an alpha
+ * channel, then @ref JxlEncoderSetExtraChannelInfo must be called between
+ * JxlEncoderSetBasicInfo and @ref JxlEncoderAddImageFrame. In order to indicate
+ * extra channels, the value of `info.num_extra_channels` should be set to the
+ * number of extra channels, also counting the alpha channel if present.
+ *
+ * @param enc encoder object.
+ * @param info global image metadata. Object owned by the caller and its
+ * contents are copied internally.
+ * @return JXL_ENC_SUCCESS if the operation was successful,
+ * JXL_ENC_ERROR or JXL_ENC_NOT_SUPPORTED otherwise
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetBasicInfo(JxlEncoder* enc,
+ const JxlBasicInfo* info);
+
+/**
+ * Sets the upsampling method the decoder will use in case there are frames
+ * with JXL_ENC_FRAME_SETTING_RESAMPLING set. This is useful in combination
+ * with the JXL_ENC_FRAME_SETTING_ALREADY_DOWNSAMPLED option, to control the
+ * type of upsampling that will be used.
+ *
+ * @param enc encoder object.
+ * @param factor upsampling factor to configure (1, 2, 4 or 8; for 1 this
+ * function has no effect at all)
+ * @param mode upsampling mode to use for this upsampling:
+ * -1: default (good for photographic images, no signaling overhead)
+ * 0: nearest neighbor (good for pixel art)
+ * 1: 'pixel dots' (same as NN for 2x, diamond-shaped 'pixel dots' for 4x/8x)
+ * @return JXL_ENC_SUCCESS if the operation was successful,
+ * JXL_ENC_ERROR or JXL_ENC_NOT_SUPPORTED otherwise
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetUpsamplingMode(JxlEncoder* enc,
+ int64_t factor,
+ int64_t mode);
+
+/**
+ * Initializes a JxlExtraChannelInfo struct to default values.
+ * For forwards-compatibility, this function has to be called before values
+ * are assigned to the struct fields.
+ * The default values correspond to an 8-bit channel of the provided type.
+ *
+ * @param type type of the extra channel.
+ * @param info global extra channel metadata. Object owned by the caller and its
+ * contents are copied internally.
+ */
+JXL_EXPORT void JxlEncoderInitExtraChannelInfo(JxlExtraChannelType type,
+ JxlExtraChannelInfo* info);
+
+/**
+ * Sets information for the extra channel at the given index. The index
+ * must be smaller than num_extra_channels in the associated JxlBasicInfo.
+ *
+ * @param enc encoder object
+ * @param index index of the extra channel to set.
+ * @param info global extra channel metadata. Object owned by the caller and its
+ * contents are copied internally.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelInfo(
+ JxlEncoder* enc, size_t index, const JxlExtraChannelInfo* info);
+
+/**
+ * Sets the name for the extra channel at the given index in UTF-8. The index
+ * must be smaller than the num_extra_channels in the associated JxlBasicInfo.
+ *
+ * TODO(lode): remove size parameter for consistency with
+ * JxlEncoderSetFrameName
+ *
+ * @param enc encoder object
+ * @param index index of the extra channel to set.
+ * @param name buffer with the name of the extra channel.
+ * @param size size of the name buffer in bytes, not counting the terminating
+ * character.
+ * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelName(JxlEncoder* enc,
+ size_t index,
+ const char* name,
+ size_t size);
+
+/**
+ * Sets a frame-specific option of integer type to the encoder options.
+ * The JxlEncoderFrameSettingId argument determines which option is set.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param option ID of the option to set.
+ * @param value Integer value to set for this option.
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR in
+ * case of an error, such as invalid or unknown option id, or invalid integer
+ * value for the given option. If an error is returned, the state of the
+ * JxlEncoderFrameSettings object is still valid and is the same as before this
+ * function was called.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetOption(
+ JxlEncoderFrameSettings* frame_settings, JxlEncoderFrameSettingId option,
+ int64_t value);
+
+/**
+ * Sets a frame-specific option of float type to the encoder options.
+ * The JxlEncoderFrameSettingId argument determines which option is set.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param option ID of the option to set.
+ * @param value Float value to set for this option.
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR in
+ * case of an error, such as invalid or unknown option id, or invalid integer
+ * value for the given option. If an error is returned, the state of the
+ * JxlEncoderFrameSettings object is still valid and is the same as before this
+ * function was called.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetFloatOption(
+ JxlEncoderFrameSettings* frame_settings, JxlEncoderFrameSettingId option,
+ float value);
+
+/** Forces the encoder to use the box-based container format (BMFF) even
+ * when not necessary.
+ *
+ * When using @ref JxlEncoderUseBoxes, @ref JxlEncoderStoreJPEGMetadata or @ref
+ * JxlEncoderSetCodestreamLevel with level 10, the encoder will automatically
+ * also use the container format, it is not necessary to use
+ * JxlEncoderUseContainer for those use cases.
+ *
+ * By default this setting is disabled.
+ *
+ * This setting can only be set at the beginning, before encoding starts.
+ *
+ * @param enc encoder object.
+ * @param use_container true if the encoder should always output the JPEG XL
+ * container format, false to only output it when necessary.
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
+ * otherwise.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderUseContainer(JxlEncoder* enc,
+ JXL_BOOL use_container);
+
+/**
+ * Configure the encoder to store JPEG reconstruction metadata in the JPEG XL
+ * container.
+ *
+ * If this is set to true and a single JPEG frame is added, it will be
+ * possible to losslessly reconstruct the JPEG codestream.
+ *
+ * This setting can only be set at the beginning, before encoding starts.
+ *
+ * @param enc encoder object.
+ * @param store_jpeg_metadata true if the encoder should store JPEG metadata.
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
+ * otherwise.
+ */
+JXL_EXPORT JxlEncoderStatus
+JxlEncoderStoreJPEGMetadata(JxlEncoder* enc, JXL_BOOL store_jpeg_metadata);
+
+/** Sets the feature level of the JPEG XL codestream. Valid values are 5 and
+ * 10, or -1 (to choose automatically). Using the minimum required level, or
+ * level 5 in most cases, is recommended for compatibility with all decoders.
+ *
+ * Level 5: for end-user image delivery, this level is the most widely
+ * supported level by image decoders and the recommended level to use unless a
+ * level 10 feature is absolutely necessary. Supports a maximum resolution
+ * 268435456 pixels total with a maximum width or height of 262144 pixels,
+ * maximum 16-bit color channel depth, maximum 120 frames per second for
+ * animation, maximum ICC color profile size of 4 MiB, it allows all color
+ * models and extra channel types except CMYK and the JXL_CHANNEL_BLACK extra
+ * channel, and a maximum of 4 extra channels in addition to the 3 color
+ * channels. It also sets boundaries to certain internally used coding tools.
+ *
+ * Level 10: this level removes or increases the bounds of most of the level
+ * 5 limitations, allows CMYK color and up to 32 bits per color channel, but
+ * may be less widely supported.
+ *
+ * The default value is -1. This means the encoder will automatically choose
+ * between level 5 and level 10 based on what information is inside the @ref
+ * JxlBasicInfo structure. Do note that some level 10 features, particularly
+ * those used by animated JPEG XL codestreams, might require level 10, even
+ * though the @ref JxlBasicInfo only suggests level 5. In this case, the level
+ * must be explicitly set to 10, otherwise the encoder will return an error.
+ * The encoder will restrict internal encoding choices to those compatible with
+ * the level setting.
+ *
+ * This setting can only be set at the beginning, before encoding starts.
+ *
+ * @param enc encoder object.
+ * @param level the level value to set, must be -1, 5, or 10.
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
+ * otherwise.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetCodestreamLevel(JxlEncoder* enc,
+ int level);
+
+/** Returns the codestream level required to support the currently configured
+ * settings and basic info. This function can only be used at the beginning,
+ * before encoding starts, but after setting basic info.
+ *
+ * This does not support per-frame settings, only global configuration, such as
+ * the image dimensions, that are known at the time of writing the header of
+ * the JPEG XL file.
+ *
+ * If this returns 5, nothing needs to be done and the codestream can be
+ * compatible with any decoder. If this returns 10, JxlEncoderSetCodestreamLevel
+ * has to be used to set the codestream level to 10, or the encoder can be
+ * configured differently to allow using the more compatible level 5.
+ *
+ * @param enc encoder object.
+ * @return -1 if no level can support the configuration (e.g. image dimensions
+ * larger than even level 10 supports), 5 if level 5 is supported, 10 if setting
+ * the codestream level to 10 is required.
+ *
+ */
+JXL_EXPORT int JxlEncoderGetRequiredCodestreamLevel(const JxlEncoder* enc);
+
+/**
+ * Enables lossless encoding.
+ *
+ * This is not an option like the others on itself, but rather while enabled it
+ * overrides a set of existing options (such as distance, modular mode and
+ * color transform) that enables bit-for-bit lossless encoding.
+ *
+ * When disabled, those options are not overridden, but since those options
+ * could still have been manually set to a combination that operates losslessly,
+ * using this function with lossless set to JXL_DEC_FALSE does not guarantee
+ * lossy encoding, though the default set of options is lossy.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param lossless whether to override options for lossless mode
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
+ * otherwise.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameLossless(
+ JxlEncoderFrameSettings* frame_settings, JXL_BOOL lossless);
+
+/**
+ * Sets the distance level for lossy compression: target max butteraugli
+ * distance, lower = higher quality. Range: 0 .. 25.
+ * 0.0 = mathematically lossless (however, use JxlEncoderSetFrameLossless
+ * instead to use true lossless, as setting distance to 0 alone is not the only
+ * requirement). 1.0 = visually lossless. Recommended range: 0.5 .. 3.0. Default
+ * value: 1.0.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param distance the distance value to set.
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
+ * otherwise.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameDistance(
+ JxlEncoderFrameSettings* frame_settings, float distance);
+
+/**
+ * Sets the distance level for lossy compression of extra channels.
+ * The distance is as in JxlEncoderSetFrameDistance (lower = higher quality).
+ * If not set, or if set to the special value -1, the distance that was set with
+ * JxlEncoderSetFrameDistance will be used.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param index index of the extra channel to set a distance value for.
+ * @param distance the distance value to set.
+ * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
+ * otherwise.
+ */
+JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelDistance(
+ JxlEncoderFrameSettings* frame_settings, size_t index, float distance);
+
+/**
+ * Maps JPEG-style quality factor to distance.
+ *
+ * This function takes in input a JPEG-style quality factor `quality` and
+ * produces as output a `distance` value suitable to be used with @ref
+ * JxlEncoderSetFrameDistance and
+ * @ref JxlEncoderSetExtraChannelDistance.
+ *
+ * The `distance` value influences the level of compression, with lower values
+ * indicating higher quality:
+ * - 0.0 implies lossless compression (however, note that calling @ref
+ * JxlEncoderSetFrameLossless is required).
+ * - 1.0 represents a visually lossy compression, which is also the default
+ * setting.
+ *
+ * The `quality` parameter, ranging up to 100, is inversely related to
+ * 'distance':
+ * - A `quality` of 100.0 maps to a `distance` of 0.0 (lossless).
+ * - A `quality` of 90.0 corresponds to a `distance` of 1.0.
+ *
+ * Recommended Range:
+ * - `distance`: 0.5 to 3.0.
+ * - corresponding `quality`: approximately 96 to 68.
+ *
+ * Allowed Range:
+ * - `distance`: 0.0 to 25.0.
+ * - corresponding `quality`: 100.0 to 0.0.
+ *
+ * Note: the `quality` parameter has no consistent psychovisual meaning
+ * across different codecs and libraries. Using the mapping defined by @ref
+ * JxlEncoderDistanceFromQuality will result in a visual quality roughly
+ * equivalent to what would be obtained with `libjpeg-turbo` with the same
+ * `quality` parameter, but that is by no means guaranteed; do not assume that
+ * the same quality value will result in similar file sizes and image quality
+ * across different codecs.
+ */
+JXL_EXPORT float JxlEncoderDistanceFromQuality(float quality);
+
+/**
+ * Create a new set of encoder options, with all values initially copied from
+ * the @p source options, or set to default if @p source is NULL.
+ *
+ * The returned pointer is an opaque struct tied to the encoder and it will be
+ * deallocated by the encoder when JxlEncoderDestroy() is called. For functions
+ * taking both a @ref JxlEncoder and a @ref JxlEncoderFrameSettings, only
+ * JxlEncoderFrameSettings created with this function for the same encoder
+ * instance can be used.
+ *
+ * @param enc encoder object.
+ * @param source source options to copy initial values from, or NULL to get
+ * defaults initialized to defaults.
+ * @return the opaque struct pointer identifying a new set of encoder options.
+ */
+JXL_EXPORT JxlEncoderFrameSettings* JxlEncoderFrameSettingsCreate(
+ JxlEncoder* enc, const JxlEncoderFrameSettings* source);
+
+/**
+ * Sets a color encoding to be sRGB.
+ *
+ * @param color_encoding color encoding instance.
+ * @param is_gray whether the color encoding should be gray scale or color.
+ */
+JXL_EXPORT void JxlColorEncodingSetToSRGB(JxlColorEncoding* color_encoding,
+ JXL_BOOL is_gray);
+
+/**
+ * Sets a color encoding to be linear sRGB.
+ *
+ * @param color_encoding color encoding instance.
+ * @param is_gray whether the color encoding should be gray scale or color.
+ */
+JXL_EXPORT void JxlColorEncodingSetToLinearSRGB(
+ JxlColorEncoding* color_encoding, JXL_BOOL is_gray);
+
+/**
+ * Enables usage of expert options.
+ *
+ * At the moment, the only expert option is setting an effort value of 10,
+ * which gives the best compression for pixel-lossless modes but is very slow.
+ *
+ * @param enc encoder object.
+ */
+JXL_EXPORT void JxlEncoderAllowExpertOptions(JxlEncoder* enc);
+
+/**
+ * Function type for @ref JxlEncoderSetDebugImageCallback.
+ *
+ * The callback may be called simultaneously by different threads when using a
+ * threaded parallel runner, on different debug images.
+ *
+ * @param opaque optional user data, as given to @ref
+ * JxlEncoderSetDebugImageCallback.
+ * @param label label of debug image, can be used in filenames
+ * @param xsize width of debug image
+ * @param ysize height of debug image
+ * @param color color encoding of debug image
+ * @param pixels pixel data of debug image as big-endian 16-bit unsigned
+ * samples. The memory is not owned by the user, and is only valid during the
+ * time the callback is running.
+ */
+typedef void (*JxlDebugImageCallback)(void* opaque, const char* label,
+ size_t xsize, size_t ysize,
+ const JxlColorEncoding* color,
+ const uint16_t* pixels);
+
+/**
+ * Sets the given debug image callback that will be used by the encoder to
+ * output various debug images during encoding.
+ *
+ * This only has any effect if the encoder was compiled with the appropriate
+ * debug build flags.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param callback used to return the debug image
+ * @param opaque user supplied parameter to the image callback
+ */
+JXL_EXPORT void JxlEncoderSetDebugImageCallback(
+ JxlEncoderFrameSettings* frame_settings, JxlDebugImageCallback callback,
+ void* opaque);
+
+/**
+ * Sets the given stats object for gathering various statistics during encoding.
+ *
+ * This only has any effect if the encoder was compiled with the appropriate
+ * debug build flags.
+ *
+ * @param frame_settings set of options and metadata for this frame. Also
+ * includes reference to the encoder object.
+ * @param stats object that can be used to query the gathered stats (created
+ * by @ref JxlEncoderStatsCreate)
+ */
+JXL_EXPORT void JxlEncoderCollectStats(JxlEncoderFrameSettings* frame_settings,
+ JxlEncoderStats* stats);
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_ENCODE_H_ */
+
+/** @}*/
diff --git a/third_party/jpeg-xl/lib/include/jxl/encode_cxx.h b/third_party/jpeg-xl/lib/include/jxl/encode_cxx.h
new file mode 100644
index 0000000000..13adb8683c
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/encode_cxx.h
@@ -0,0 +1,58 @@
+// Copyright (c) the JPEG XL Project Authors. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/// @addtogroup libjxl_cpp
+///@{
+///
+/// @file encode_cxx.h
+/// @brief C++ header-only helper for @ref encode.h.
+///
+/// There's no binary library associated with the header since this is a header
+/// only library.
+
+#ifndef JXL_ENCODE_CXX_H_
+#define JXL_ENCODE_CXX_H_
+
+#include <jxl/encode.h>
+#include <jxl/memory_manager.h>
+
+#include <memory>
+
+#if !(defined(__cplusplus) || defined(c_plusplus))
+#error "This a C++ only header. Use jxl/encode.h from C sources."
+#endif
+
+/// Struct to call JxlEncoderDestroy from the JxlEncoderPtr unique_ptr.
+struct JxlEncoderDestroyStruct {
+ /// Calls @ref JxlEncoderDestroy() on the passed encoder.
+ void operator()(JxlEncoder* encoder) { JxlEncoderDestroy(encoder); }
+};
+
+/// std::unique_ptr<> type that calls JxlEncoderDestroy() when releasing the
+/// encoder.
+///
+/// Use this helper type from C++ sources to ensure the encoder is destroyed and
+/// their internal resources released.
+typedef std::unique_ptr<JxlEncoder, JxlEncoderDestroyStruct> JxlEncoderPtr;
+
+/// Creates an instance of JxlEncoder into a JxlEncoderPtr and initializes it.
+///
+/// This function returns a unique_ptr that will call JxlEncoderDestroy() when
+/// releasing the pointer. See @ref JxlEncoderCreate for details on the
+/// instance creation.
+///
+/// @param memory_manager custom allocator function. It may be NULL. The memory
+/// manager will be copied internally.
+/// @return a @c NULL JxlEncoderPtr if the instance can not be allocated or
+/// initialized
+/// @return initialized JxlEncoderPtr instance otherwise.
+static inline JxlEncoderPtr JxlEncoderMake(
+ const JxlMemoryManager* memory_manager) {
+ return JxlEncoderPtr(JxlEncoderCreate(memory_manager));
+}
+
+#endif // JXL_ENCODE_CXX_H_
+
+/// @}
diff --git a/third_party/jpeg-xl/lib/include/jxl/memory_manager.h b/third_party/jpeg-xl/lib/include/jxl/memory_manager.h
new file mode 100644
index 0000000000..52640a8beb
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/memory_manager.h
@@ -0,0 +1,72 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_common
+ * @{
+ * @file memory_manager.h
+ * @brief Abstraction functions used by JPEG XL to allocate memory.
+ */
+
+#ifndef JXL_MEMORY_MANAGER_H_
+#define JXL_MEMORY_MANAGER_H_
+
+#include <stddef.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/**
+ * Allocating function for a memory region of a given size.
+ *
+ * Allocates a contiguous memory region of size @p size bytes. The returned
+ * memory may not be aligned to a specific size or initialized at all.
+ *
+ * @param opaque custom memory manager handle provided by the caller.
+ * @param size in bytes of the requested memory region.
+ * @return @c NULL if the memory can not be allocated,
+ * @return pointer to the memory otherwise.
+ */
+typedef void* (*jpegxl_alloc_func)(void* opaque, size_t size);
+
+/**
+ * Deallocating function pointer type.
+ *
+ * This function @b MUST do nothing if @p address is @c NULL.
+ *
+ * @param opaque custom memory manager handle provided by the caller.
+ * @param address memory region pointer returned by ::jpegxl_alloc_func, or @c
+ * NULL.
+ */
+typedef void (*jpegxl_free_func)(void* opaque, void* address);
+
+/**
+ * Memory Manager struct.
+ * These functions, when provided by the caller, will be used to handle memory
+ * allocations.
+ */
+typedef struct JxlMemoryManagerStruct {
+ /** The opaque pointer that will be passed as the first parameter to all the
+ * functions in this struct. */
+ void* opaque;
+
+ /** Memory allocation function. This can be NULL if and only if also the
+ * free() member in this class is NULL. All dynamic memory will be allocated
+ * and freed with these functions if they are not NULL. */
+ jpegxl_alloc_func alloc;
+ /** Free function matching the alloc() member. */
+ jpegxl_free_func free;
+
+ /* TODO(deymo): Add cache-aligned alloc/free functions here. */
+} JxlMemoryManager;
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_MEMORY_MANAGER_H_ */
+
+/** @}*/
diff --git a/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h b/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h
new file mode 100644
index 0000000000..e71e0aa926
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h
@@ -0,0 +1,156 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_threads
+ * @{
+ */
+/**
+ * @file parallel_runner.h
+ */
+
+/** API for running data operations in parallel in a multi-threaded environment.
+ * This module allows the JPEG XL caller to define their own way of creating and
+ * assigning threads.
+ *
+ * The JxlParallelRunner function type defines a parallel data processing
+ * runner that may be implemented by the caller to allow the library to process
+ * in multiple threads. The multi-threaded processing in this library only
+ * requires to run the same function over each number of a range, possibly
+ * running each call in a different thread. The JPEG XL caller is responsible
+ * for implementing this logic using the thread APIs available in their system.
+ * For convenience, a C++ implementation based on std::thread is provided in
+ * jpegxl/parallel_runner_thread.h (part of the jpegxl_threads library).
+ *
+ * Thread pools usually store small numbers of heterogeneous tasks in a queue.
+ * When tasks are identical or differ only by an integer input parameter, it is
+ * much faster to store just one function of an integer parameter and call it
+ * for each value. Conventional vector-of-tasks can be run in parallel using a
+ * lambda function adapter that simply calls task_funcs[task].
+ *
+ * If no multi-threading is desired, a @c NULL value of JxlParallelRunner
+ * will use an internal implementation without multi-threading.
+ */
+
+#ifndef JXL_PARALLEL_RUNNER_H_
+#define JXL_PARALLEL_RUNNER_H_
+
+#include <stddef.h>
+#include <stdint.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/** Return code used in the JxlParallel* functions as return value. A value
+ * of 0 means success and any other value means error. The special value
+ * JXL_PARALLEL_RET_RUNNER_ERROR can be used by the runner to indicate any
+ * other error.
+ */
+typedef int JxlParallelRetCode;
+
+/**
+ * General error returned by the JxlParallelRunInit function to indicate
+ * an error.
+ */
+#define JXL_PARALLEL_RET_RUNNER_ERROR (-1)
+
+/**
+ * Parallel run initialization callback. See JxlParallelRunner for details.
+ *
+ * This function MUST be called by the JxlParallelRunner only once, on the
+ * same thread that called JxlParallelRunner, before any parallel execution.
+ * The purpose of this call is to provide the maximum number of threads that the
+ * JxlParallelRunner will use, which can be used by JPEG XL to allocate
+ * per-thread storage if needed.
+ *
+ * @param jpegxl_opaque the @p jpegxl_opaque handle provided to
+ * JxlParallelRunner() must be passed here.
+ * @param num_threads the maximum number of threads. This value must be
+ * positive.
+ * @return 0 if the initialization process was successful.
+ * @return an error code if there was an error, which should be returned by
+ * JxlParallelRunner().
+ */
+typedef JxlParallelRetCode (*JxlParallelRunInit)(void* jpegxl_opaque,
+ size_t num_threads);
+
+/**
+ * Parallel run data processing callback. See JxlParallelRunner for details.
+ *
+ * This function MUST be called once for every number in the range [start_range,
+ * end_range) (including start_range but not including end_range) passing this
+ * number as the @p value. Calls for different value may be executed from
+ * different threads in parallel.
+ *
+ * @param jpegxl_opaque the @p jpegxl_opaque handle provided to
+ * JxlParallelRunner() must be passed here.
+ * @param value the number in the range [start_range, end_range) of the call.
+ * @param thread_id the thread number where this function is being called from.
+ * This must be lower than the @p num_threads value passed to
+ * JxlParallelRunInit.
+ */
+typedef void (*JxlParallelRunFunction)(void* jpegxl_opaque, uint32_t value,
+ size_t thread_id);
+
+/**
+ * JxlParallelRunner function type. A parallel runner implementation can be
+ * provided by a JPEG XL caller to allow running computations in multiple
+ * threads. This function must call the initialization function @p init in the
+ * same thread that called it and then call the passed @p func once for every
+ * number in the range [start_range, end_range) (including start_range but not
+ * including end_range) possibly from different multiple threads in parallel.
+ *
+ * The JxlParallelRunner function does not need to be re-entrant. This means
+ * that the same JxlParallelRunner function with the same runner_opaque
+ * provided parameter will not be called from the library from either @p init or
+ * @p func in the same decoder or encoder instance. However, a single decoding
+ * or encoding instance may call the provided JxlParallelRunner multiple
+ * times for different parts of the decoding or encoding process.
+ *
+ * @return 0 if the @p init call succeeded (returned 0) and no other error
+ * occurred in the runner code.
+ * @return JXL_PARALLEL_RET_RUNNER_ERROR if an error occurred in the runner
+ * code, for example, setting up the threads.
+ * @return the return value of @p init() if non-zero.
+ */
+typedef JxlParallelRetCode (*JxlParallelRunner)(
+ void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init,
+ JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range);
+
+/* The following is an example of a JxlParallelRunner that doesn't use any
+ * multi-threading. Note that this implementation doesn't store any state
+ * between multiple calls of the ExampleSequentialRunner function, so the
+ * runner_opaque value is not used.
+
+ JxlParallelRetCode ExampleSequentialRunner(void* runner_opaque,
+ void* jpegxl_opaque,
+ JxlParallelRunInit init,
+ JxlParallelRunFunction func,
+ uint32_t start_range,
+ uint32_t end_range) {
+ // We only use one thread (the currently running thread).
+ JxlParallelRetCode init_ret = (*init)(jpegxl_opaque, 1);
+ if (init_ret != 0) return init_ret;
+
+ // In case of other initialization error (for example when initializing the
+ // threads) one can return JXL_PARALLEL_RET_RUNNER_ERROR.
+
+ for (uint32_t i = start_range; i < end_range; i++) {
+ // Every call is in the thread number 0. These don't need to be in any
+ // order.
+ (*func)(jpegxl_opaque, i, 0);
+ }
+ return 0;
+ }
+ */
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_PARALLEL_RUNNER_H_ */
+
+/** @}*/
diff --git a/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h b/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h
new file mode 100644
index 0000000000..a65015d861
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h
@@ -0,0 +1,77 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_threads
+ * @{
+ * @file resizable_parallel_runner.h
+ * @brief implementation using std::thread of a resizeable ::JxlParallelRunner.
+ */
+
+/** Implementation of JxlParallelRunner than can be used to enable
+ * multithreading when using the JPEG XL library. This uses std::thread
+ * internally and related synchronization functions. The number of threads
+ * created can be changed after creation of the thread pool; the threads
+ * (including the main thread) are re-used for every
+ * ResizableParallelRunner::Runner call. Only one concurrent
+ * JxlResizableParallelRunner call per instance is allowed at a time.
+ *
+ * This is a scalable, lower-overhead thread pool runner, especially suitable
+ * for data-parallel computations in the fork-join model, where clients need to
+ * know when all tasks have completed.
+ *
+ * Compared to the implementation in @ref thread_parallel_runner.h, this
+ * implementation is tuned for execution on lower-powered systems, including
+ * for example ARM CPUs with big.LITTLE computation models.
+ */
+
+#ifndef JXL_RESIZABLE_PARALLEL_RUNNER_H_
+#define JXL_RESIZABLE_PARALLEL_RUNNER_H_
+
+#include <jxl/jxl_threads_export.h>
+#include <jxl/memory_manager.h>
+#include <jxl/parallel_runner.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/** Parallel runner internally using std::thread. Use as JxlParallelRunner.
+ */
+JXL_THREADS_EXPORT JxlParallelRetCode JxlResizableParallelRunner(
+ void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init,
+ JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range);
+
+/** Creates the runner for JxlResizableParallelRunner. Use as the opaque
+ * runner. The runner will execute tasks on the calling thread until
+ * @ref JxlResizableParallelRunnerSetThreads is called.
+ */
+JXL_THREADS_EXPORT void* JxlResizableParallelRunnerCreate(
+ const JxlMemoryManager* memory_manager);
+
+/** Changes the number of threads for JxlResizableParallelRunner.
+ */
+JXL_THREADS_EXPORT void JxlResizableParallelRunnerSetThreads(
+ void* runner_opaque, size_t num_threads);
+
+/** Suggests a number of threads to use for an image of given size.
+ */
+JXL_THREADS_EXPORT uint32_t
+JxlResizableParallelRunnerSuggestThreads(uint64_t xsize, uint64_t ysize);
+
+/** Destroys the runner created by JxlResizableParallelRunnerCreate.
+ */
+JXL_THREADS_EXPORT void JxlResizableParallelRunnerDestroy(void* runner_opaque);
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_RESIZABLE_PARALLEL_RUNNER_H_ */
+
+/** @}*/
diff --git a/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner_cxx.h b/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner_cxx.h
new file mode 100644
index 0000000000..84ba82772a
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner_cxx.h
@@ -0,0 +1,65 @@
+// Copyright (c) the JPEG XL Project Authors. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/// @addtogroup libjxl_cpp
+/// @{
+///
+/// @file resizable_parallel_runner_cxx.h
+/// @ingroup libjxl_threads
+/// @brief C++ header-only helper for @ref resizable_parallel_runner.h.
+///
+/// There's no binary library associated with the header since this is a header
+/// only library.
+
+#ifndef JXL_RESIZABLE_PARALLEL_RUNNER_CXX_H_
+#define JXL_RESIZABLE_PARALLEL_RUNNER_CXX_H_
+
+#include <jxl/memory_manager.h>
+#include <jxl/resizable_parallel_runner.h>
+
+#include <memory>
+
+#if !(defined(__cplusplus) || defined(c_plusplus))
+#error \
+ "This a C++ only header. Use jxl/jxl_resizable_parallel_runner.h from C" \
+ "sources."
+#endif
+
+/// Struct to call JxlResizableParallelRunnerDestroy from the
+/// JxlResizableParallelRunnerPtr unique_ptr.
+struct JxlResizableParallelRunnerDestroyStruct {
+ /// Calls @ref JxlResizableParallelRunnerDestroy() on the passed runner.
+ void operator()(void* runner) { JxlResizableParallelRunnerDestroy(runner); }
+};
+
+/// std::unique_ptr<> type that calls JxlResizableParallelRunnerDestroy() when
+/// releasing the runner.
+///
+/// Use this helper type from C++ sources to ensure the runner is destroyed and
+/// their internal resources released.
+typedef std::unique_ptr<void, JxlResizableParallelRunnerDestroyStruct>
+ JxlResizableParallelRunnerPtr;
+
+/// Creates an instance of JxlResizableParallelRunner into a
+/// JxlResizableParallelRunnerPtr and initializes it.
+///
+/// This function returns a unique_ptr that will call
+/// JxlResizableParallelRunnerDestroy() when releasing the pointer. See @ref
+/// JxlResizableParallelRunnerCreate for details on the instance creation.
+///
+/// @param memory_manager custom allocator function. It may be NULL. The memory
+/// manager will be copied internally.
+/// @return a @c NULL JxlResizableParallelRunnerPtr if the instance can not be
+/// allocated or initialized
+/// @return initialized JxlResizableParallelRunnerPtr instance otherwise.
+static inline JxlResizableParallelRunnerPtr JxlResizableParallelRunnerMake(
+ const JxlMemoryManager* memory_manager) {
+ return JxlResizableParallelRunnerPtr(
+ JxlResizableParallelRunnerCreate(memory_manager));
+}
+
+#endif // JXL_RESIZABLE_PARALLEL_RUNNER_CXX_H_
+
+/// @}
diff --git a/third_party/jpeg-xl/lib/include/jxl/stats.h b/third_party/jpeg-xl/lib/include/jxl/stats.h
new file mode 100644
index 0000000000..c9359dc870
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/stats.h
@@ -0,0 +1,103 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_encoder
+ * @{
+ * @file stats.h
+ * @brief API to collect various statistics from JXL encoder.
+ */
+
+#ifndef JXL_STATS_H_
+#define JXL_STATS_H_
+
+#include <jxl/jxl_export.h>
+#include <stddef.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/**
+ * Opaque structure that holds the encoder statistics.
+ *
+ * Allocated and initialized with JxlEncoderStatsCreate().
+ * Cleaned up and deallocated with JxlEncoderStatsDestroy().
+ */
+typedef struct JxlEncoderStatsStruct JxlEncoderStats;
+
+/**
+ * Creates an instance of JxlEncoderStats and initializes it.
+ *
+ * @return pointer to initialized JxlEncoderStats instance
+ */
+JXL_EXPORT JxlEncoderStats* JxlEncoderStatsCreate(void);
+
+/**
+ * Deinitializes and frees JxlEncoderStats instance.
+ *
+ * @param stats instance to be cleaned up and deallocated. No-op if stats is
+ * null pointer.
+ */
+JXL_EXPORT void JxlEncoderStatsDestroy(JxlEncoderStats* stats);
+
+/** Data type for querying JxlEncoderStats object
+ */
+typedef enum {
+ JXL_ENC_STAT_HEADER_BITS,
+ JXL_ENC_STAT_TOC_BITS,
+ JXL_ENC_STAT_DICTIONARY_BITS,
+ JXL_ENC_STAT_SPLINES_BITS,
+ JXL_ENC_STAT_NOISE_BITS,
+ JXL_ENC_STAT_QUANT_BITS,
+ JXL_ENC_STAT_MODULAR_TREE_BITS,
+ JXL_ENC_STAT_MODULAR_GLOBAL_BITS,
+ JXL_ENC_STAT_DC_BITS,
+ JXL_ENC_STAT_MODULAR_DC_GROUP_BITS,
+ JXL_ENC_STAT_CONTROL_FIELDS_BITS,
+ JXL_ENC_STAT_COEF_ORDER_BITS,
+ JXL_ENC_STAT_AC_HISTOGRAM_BITS,
+ JXL_ENC_STAT_AC_BITS,
+ JXL_ENC_STAT_MODULAR_AC_GROUP_BITS,
+ JXL_ENC_STAT_NUM_SMALL_BLOCKS,
+ JXL_ENC_STAT_NUM_DCT4X8_BLOCKS,
+ JXL_ENC_STAT_NUM_AFV_BLOCKS,
+ JXL_ENC_STAT_NUM_DCT8_BLOCKS,
+ JXL_ENC_STAT_NUM_DCT8X32_BLOCKS,
+ JXL_ENC_STAT_NUM_DCT16_BLOCKS,
+ JXL_ENC_STAT_NUM_DCT16X32_BLOCKS,
+ JXL_ENC_STAT_NUM_DCT32_BLOCKS,
+ JXL_ENC_STAT_NUM_DCT32X64_BLOCKS,
+ JXL_ENC_STAT_NUM_DCT64_BLOCKS,
+ JXL_ENC_STAT_NUM_BUTTERAUGLI_ITERS,
+ JXL_ENC_NUM_STATS,
+} JxlEncoderStatsKey;
+
+/** Returns the value of the statistics corresponding the given key.
+ *
+ * @param stats object that was passed to the encoder with a
+ * @ref JxlEncoderCollectStats function
+ * @param key the particular statistics to query
+ *
+ * @return the value of the statistics
+ */
+JXL_EXPORT size_t JxlEncoderStatsGet(const JxlEncoderStats* stats,
+ JxlEncoderStatsKey key);
+
+/** Updates the values of the given stats object with that of an other.
+ *
+ * @param stats object whose values will be updated (usually added together)
+ * @param other stats object whose values will be merged with stats
+ */
+JXL_EXPORT void JxlEncoderStatsMerge(JxlEncoderStats* stats,
+ const JxlEncoderStats* other);
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_STATS_H_ */
+
+/** @}*/
diff --git a/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h b/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h
new file mode 100644
index 0000000000..6166fe7d36
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h
@@ -0,0 +1,71 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_threads
+ * @{
+ * @file thread_parallel_runner.h
+ * @brief implementation using std::thread of a ::JxlParallelRunner.
+ */
+
+/** Implementation of JxlParallelRunner than can be used to enable
+ * multithreading when using the JPEG XL library. This uses std::thread
+ * internally and related synchronization functions. The number of threads
+ * created is fixed at construction time and the threads are re-used for every
+ * ThreadParallelRunner::Runner call. Only one concurrent
+ * JxlThreadParallelRunner call per instance is allowed at a time.
+ *
+ * This is a scalable, lower-overhead thread pool runner, especially suitable
+ * for data-parallel computations in the fork-join model, where clients need to
+ * know when all tasks have completed.
+ *
+ * This thread pool can efficiently load-balance millions of tasks using an
+ * atomic counter, thus avoiding per-task virtual or system calls. With 48
+ * hyperthreads and 1M tasks that add to an atomic counter, overall runtime is
+ * 10-20x higher when using std::async, and ~200x for a queue-based thread
+ */
+
+#ifndef JXL_THREAD_PARALLEL_RUNNER_H_
+#define JXL_THREAD_PARALLEL_RUNNER_H_
+
+#include <jxl/jxl_threads_export.h>
+#include <jxl/memory_manager.h>
+#include <jxl/parallel_runner.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/** Parallel runner internally using std::thread. Use as JxlParallelRunner.
+ */
+JXL_THREADS_EXPORT JxlParallelRetCode JxlThreadParallelRunner(
+ void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init,
+ JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range);
+
+/** Creates the runner for JxlThreadParallelRunner. Use as the opaque
+ * runner.
+ */
+JXL_THREADS_EXPORT void* JxlThreadParallelRunnerCreate(
+ const JxlMemoryManager* memory_manager, size_t num_worker_threads);
+
+/** Destroys the runner created by JxlThreadParallelRunnerCreate.
+ */
+JXL_THREADS_EXPORT void JxlThreadParallelRunnerDestroy(void* runner_opaque);
+
+/** Returns a default num_worker_threads value for
+ * JxlThreadParallelRunnerCreate.
+ */
+JXL_THREADS_EXPORT size_t JxlThreadParallelRunnerDefaultNumWorkerThreads(void);
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_THREAD_PARALLEL_RUNNER_H_ */
+
+/** @}*/
diff --git a/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner_cxx.h b/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner_cxx.h
new file mode 100644
index 0000000000..6c0bd4b302
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner_cxx.h
@@ -0,0 +1,66 @@
+// Copyright (c) the JPEG XL Project Authors. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/// @addtogroup libjxl_cpp
+/// @{
+///
+/// @file thread_parallel_runner_cxx.h
+/// @brief C++ header-only helper for @ref thread_parallel_runner.h.
+///
+/// There's no binary library associated with the header since this is a header
+/// only library.
+
+#ifndef JXL_THREAD_PARALLEL_RUNNER_CXX_H_
+#define JXL_THREAD_PARALLEL_RUNNER_CXX_H_
+
+#include <jxl/memory_manager.h>
+#include <jxl/thread_parallel_runner.h>
+
+#include <cstddef>
+#include <memory>
+
+#if !(defined(__cplusplus) || defined(c_plusplus))
+#error \
+ "This a C++ only header. Use jxl/jxl_thread_parallel_runner.h from C" \
+ "sources."
+#endif
+
+/// Struct to call JxlThreadParallelRunnerDestroy from the
+/// JxlThreadParallelRunnerPtr unique_ptr.
+struct JxlThreadParallelRunnerDestroyStruct {
+ /// Calls @ref JxlThreadParallelRunnerDestroy() on the passed runner.
+ void operator()(void* runner) { JxlThreadParallelRunnerDestroy(runner); }
+};
+
+/// std::unique_ptr<> type that calls JxlThreadParallelRunnerDestroy() when
+/// releasing the runner.
+///
+/// Use this helper type from C++ sources to ensure the runner is destroyed and
+/// their internal resources released.
+typedef std::unique_ptr<void, JxlThreadParallelRunnerDestroyStruct>
+ JxlThreadParallelRunnerPtr;
+
+/// Creates an instance of JxlThreadParallelRunner into a
+/// JxlThreadParallelRunnerPtr and initializes it.
+///
+/// This function returns a unique_ptr that will call
+/// JxlThreadParallelRunnerDestroy() when releasing the pointer. See @ref
+/// JxlThreadParallelRunnerCreate for details on the instance creation.
+///
+/// @param memory_manager custom allocator function. It may be NULL. The memory
+/// manager will be copied internally.
+/// @param num_worker_threads the number of worker threads to create.
+/// @return a @c NULL JxlThreadParallelRunnerPtr if the instance can not be
+/// allocated or initialized
+/// @return initialized JxlThreadParallelRunnerPtr instance otherwise.
+static inline JxlThreadParallelRunnerPtr JxlThreadParallelRunnerMake(
+ const JxlMemoryManager* memory_manager, size_t num_worker_threads) {
+ return JxlThreadParallelRunnerPtr(
+ JxlThreadParallelRunnerCreate(memory_manager, num_worker_threads));
+}
+
+#endif // JXL_THREAD_PARALLEL_RUNNER_CXX_H_
+
+/// @}
diff --git a/third_party/jpeg-xl/lib/include/jxl/types.h b/third_party/jpeg-xl/lib/include/jxl/types.h
new file mode 100644
index 0000000000..a47216f878
--- /dev/null
+++ b/third_party/jpeg-xl/lib/include/jxl/types.h
@@ -0,0 +1,154 @@
+/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file.
+ */
+
+/** @addtogroup libjxl_common
+ * @{
+ * @file types.h
+ * @brief Data types for the JPEG XL API, for both encoding and decoding.
+ */
+
+#ifndef JXL_TYPES_H_
+#define JXL_TYPES_H_
+
+#include <jxl/jxl_export.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/**
+ * A portable @c bool replacement.
+ *
+ * ::JXL_BOOL is a "documentation" type: actually it is @c int, but in API it
+ * denotes a type, whose only values are ::JXL_TRUE and ::JXL_FALSE.
+ */
+#define JXL_BOOL int
+/** Portable @c true replacement. */
+#define JXL_TRUE 1
+/** Portable @c false replacement. */
+#define JXL_FALSE 0
+/** Converts of bool-like value to either JXL_TRUE or JXL_FALSE. */
+#define TO_JXL_BOOL(C) (!!(C) ? JXL_TRUE : JXL_FALSE)
+
+/** Data type for the sample values per channel per pixel.
+ */
+typedef enum {
+ /** Use 32-bit single-precision floating point values, with range 0.0-1.0
+ * (within gamut, may go outside this range for wide color gamut). Floating
+ * point output, either JXL_TYPE_FLOAT or JXL_TYPE_FLOAT16, is recommended
+ * for HDR and wide gamut images when color profile conversion is required. */
+ JXL_TYPE_FLOAT = 0,
+
+ /** Use type uint8_t. May clip wide color gamut data.
+ */
+ JXL_TYPE_UINT8 = 2,
+
+ /** Use type uint16_t. May clip wide color gamut data.
+ */
+ JXL_TYPE_UINT16 = 3,
+
+ /** Use 16-bit IEEE 754 half-precision floating point values */
+ JXL_TYPE_FLOAT16 = 5,
+} JxlDataType;
+
+/** Ordering of multi-byte data.
+ */
+typedef enum {
+ /** Use the endianness of the system, either little endian or big endian,
+ * without forcing either specific endianness. Do not use if pixel data
+ * should be exported to a well defined format.
+ */
+ JXL_NATIVE_ENDIAN = 0,
+ /** Force little endian */
+ JXL_LITTLE_ENDIAN = 1,
+ /** Force big endian */
+ JXL_BIG_ENDIAN = 2,
+} JxlEndianness;
+
+/** Data type for the sample values per channel per pixel for the output buffer
+ * for pixels. This is not necessarily the same as the data type encoded in the
+ * codestream. The channels are interleaved per pixel. The pixels are
+ * organized row by row, left to right, top to bottom.
+ * TODO(lode): support different channel orders if needed (RGB, BGR, ...)
+ */
+typedef struct {
+ /** Amount of channels available in a pixel buffer.
+ * 1: single-channel data, e.g. grayscale or a single extra channel
+ * 2: single-channel + alpha
+ * 3: trichromatic, e.g. RGB
+ * 4: trichromatic + alpha
+ * TODO(lode): this needs finetuning. It is not yet defined how the user
+ * chooses output color space. CMYK+alpha needs 5 channels.
+ */
+ uint32_t num_channels;
+
+ /** Data type of each channel.
+ */
+ JxlDataType data_type;
+
+ /** Whether multi-byte data types are represented in big endian or little
+ * endian format. This applies to JXL_TYPE_UINT16, JXL_TYPE_UINT32
+ * and JXL_TYPE_FLOAT.
+ */
+ JxlEndianness endianness;
+
+ /** Align scanlines to a multiple of align bytes, or 0 to require no
+ * alignment at all (which has the same effect as value 1)
+ */
+ size_t align;
+} JxlPixelFormat;
+
+/** Settings for the interpretation of UINT input and output buffers.
+ * (buffers using a FLOAT data type are not affected by this)
+ */
+typedef enum {
+ /** This is the default setting, where the encoder expects the input pixels
+ * to use the full range of the pixel format data type (e.g. for UINT16, the
+ * input range is 0 .. 65535 and the value 65535 is mapped to 1.0 when
+ * converting to float), and the decoder uses the full range to output
+ * pixels. If the bit depth in the basic info is different from this, the
+ * encoder expects the values to be rescaled accordingly (e.g. multiplied by
+ * 65535/4095 for a 12-bit image using UINT16 input data type). */
+ JXL_BIT_DEPTH_FROM_PIXEL_FORMAT = 0,
+
+ /** If this setting is selected, the encoder expects the input pixels to be
+ * in the range defined by the bits_per_sample value of the basic info (e.g.
+ * for 12-bit images using UINT16 input data types, the allowed range is
+ * 0 .. 4095 and the value 4095 is mapped to 1.0 when converting to float),
+ * and the decoder outputs pixels in this range. */
+ JXL_BIT_DEPTH_FROM_CODESTREAM = 1,
+
+ /** This setting can only be used in the decoder to select a custom range for
+ * pixel output */
+ JXL_BIT_DEPTH_CUSTOM = 2,
+} JxlBitDepthType;
+
+/** Data type for describing the interpretation of the input and output buffers
+ * in terms of the range of allowed input and output pixel values. */
+typedef struct {
+ /** Bit depth setting, see comment on @ref JxlBitDepthType */
+ JxlBitDepthType type;
+
+ /** Custom bits per sample */
+ uint32_t bits_per_sample;
+
+ /** Custom exponent bits per sample */
+ uint32_t exponent_bits_per_sample;
+} JxlBitDepth;
+
+/** Data type holding the 4-character type name of an ISOBMFF box.
+ */
+typedef char JxlBoxType[4];
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* JXL_TYPES_H_ */
+
+/** @}*/