JPEG XL common definitions
JPEG XL library (libjxl)
Collaboration diagram for JPEG XL common definitions:

## Files

file | cms_interface.h
| Interface to allow the injection of different color management systems (CMSes, also called color management modules, or CMMs) in JPEG XL.
file | codestream_header.h
| 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.
file | color_encoding.h
| Color Encoding definitions used by JPEG XL. All CIE units are for the standard 1931 2 degree observer.
file | memory_manager.h
| Abstraction functions used by JPEG XL to allocate memory.
file | parallel_runner.h
file | types.h
| Data types for the JPEG XL API, for both encoding and decoding.

## Classes

struct | JxlColorProfile
struct | JxlCmsInterface
struct | JxlPreviewHeader
struct | JxlIntrinsicSizeHeader
struct | JxlAnimationHeader
struct | JxlBasicInfo
struct | JxlExtraChannelInfo
struct | JxlHeaderExtensions
struct | JxlBlendInfo
struct | JxlLayerInfo
struct | JxlFrameHeader
struct | JxlColorEncoding
struct | JxlMemoryManagerStruct
struct | JxlPixelFormat

## Macros

#define | JXL_PARALLEL_RET_RUNNER_ERROR (-1)
#define | JXL_BOOL int
#define | JXL_TRUE 1
#define | JXL_FALSE 0

## Typedefs

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)
typedef float *(* | jpegxl_cms_get_buffer_func) (void *user_data, size_t thread)
typedef JXL_BOOL(* | jpegxl_cms_run_func) (void *user_data, size_t thread, const float *input_buffer, float *output_buffer, size_t num_pixels)
typedef void(* | jpegxl_cms_destroy_func) (void *)
typedef void *(* | jpegxl_alloc_func) (void *opaque, size_t size)
typedef void(* | jpegxl_free_func) (void *opaque, void *address)
typedef struct JxlMemoryManagerStruct | JxlMemoryManager
typedef int | JxlParallelRetCode
typedef JxlParallelRetCode(* | JxlParallelRunInit) (void *jpegxl_opaque, size_t num_threads)
typedef void(* | JxlParallelRunFunction) (void *jpegxl_opaque, uint32_t value, size_t thread_id)
typedef JxlParallelRetCode(* | JxlParallelRunner) (void *runner_opaque, void *jpegxl_opaque, JxlParallelRunInit init, JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range)
typedef char | JxlBoxType[4]

## Enumerations

enum | JxlOrientation { 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 }

enum

JxlExtraChannelType {
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
}

enum | JxlBlendMode { JXL_BLEND_REPLACE = 0 , JXL_BLEND_ADD = 1 , JXL_BLEND_BLEND = 2 , JXL_BLEND_MULADD = 3 , JXL_BLEND_MUL = 4 }
enum | JxlColorSpace { JXL_COLOR_SPACE_RGB , JXL_COLOR_SPACE_GRAY , JXL_COLOR_SPACE_XYB , JXL_COLOR_SPACE_UNKNOWN }
enum | JxlWhitePoint { JXL_WHITE_POINT_D65 = 1 , JXL_WHITE_POINT_CUSTOM = 2 , JXL_WHITE_POINT_E = 10 , JXL_WHITE_POINT_DCI = 11 }
enum | JxlPrimaries { JXL_PRIMARIES_SRGB = 1 , JXL_PRIMARIES_CUSTOM = 2 , JXL_PRIMARIES_2100 = 9 , JXL_PRIMARIES_P3 = 11 }
enum | JxlTransferFunction { JXL_TRANSFER_FUNCTION_709 = 1 , JXL_TRANSFER_FUNCTION_UNKNOWN = 2 , JXL_TRANSFER_FUNCTION_LINEAR = 8 , JXL_TRANSFER_FUNCTION_SRGB = 13 , JXL_TRANSFER_FUNCTION_PQ = 16 , JXL_TRANSFER_FUNCTION_DCI = 17 , JXL_TRANSFER_FUNCTION_HLG = 18 , JXL_TRANSFER_FUNCTION_GAMMA = 65535 }
enum | JxlRenderingIntent { JXL_RENDERING_INTENT_PERCEPTUAL = 0 , JXL_RENDERING_INTENT_RELATIVE , JXL_RENDERING_INTENT_SATURATION , JXL_RENDERING_INTENT_ABSOLUTE }
enum | JxlDataType { JXL_TYPE_FLOAT = 0 , JXL_TYPE_UINT8 = 2 , JXL_TYPE_UINT16 = 3 , JXL_TYPE_FLOAT16 = 5 }
enum | JxlEndianness { JXL_NATIVE_ENDIAN = 0 , JXL_LITTLE_ENDIAN = 1 , JXL_BIG_ENDIAN = 2 }
enum | JxlProgressiveDetail { kFrames = 0 , kDC = 1 , kLastPasses = 2 , kPasses = 3 , kDCProgressive = 4 , kDCGroups = 5 , kGroups = 6 }

## Detailed Description

## Macro Definition Documentation

## JXL_BOOL

#define JXL_BOOL int

A portable `bool` replacement.

JXL_BOOL is a "documentation" type: actually it is `int`, but in API it denotes a type, whose only values are JXL_TRUE and JXL_FALSE.

## JXL_FALSE

#define JXL_FALSE 0

Portable `false` replacement.

## JXL_PARALLEL_RET_RUNNER_ERROR

#define JXL_PARALLEL_RET_RUNNER_ERROR (-1)

General error returned by the JxlParallelRunInit function to indicate an error.

## JXL_TRUE

#define JXL_TRUE 1

Portable `true` replacement.

## Typedef Documentation

## jpegxl_alloc_func

typedef void *(* jpegxl_alloc_func) (void *opaque, size_t size)

Allocating function for a memory region of a given size.

Allocates a contiguous memory region of size `size` bytes. The returned memory may not be aligned to a specific size or initialized at all.

Parameters

  opaque | custom memory manager handle provided by the caller.
  size | in bytes of the requested memory region.

Returns
  `NULL` if the memory can not be allocated,
  pointer to the memory otherwise.

## jpegxl_cms_destroy_func

typedef void(* jpegxl_cms_destroy_func) (void *)

Performs the necessary clean-up and frees the memory allocated for user data.

## jpegxl_cms_get_buffer_func

typedef float *(* jpegxl_cms_get_buffer_func) (void *user_data, size_t thread)

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 `run` function.

Parameters

  user_data | the data returned by `init`.
  thread | the index of the thread for which to return a buffer.

Returns
  A buffer that can be used by the caller for passing to `run`.

## jpegxl_cms_init_func

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)

Allocates and returns the data needed for `num_threads` parallel transforms from the `input` colorspace to `output`, with up to `pixels_per_thread` pixels to transform per call to JxlCmsInterface::run. `init_data` comes directly from the JxlCmsInterface instance. Since `run` only receives the data returned by `init`, a reference to `init_data` should be kept there if access to it is desired in `run`. Likewise for JxlCmsInterface::destroy.

The ICC data in `input` and `output` is guaranteed to outlive the `init` / `run` / `destroy` cycle.

Parameters

  init_data | JxlCmsInterface::init_data passed as-is.
  num_threads | the maximum number of threads from which JxlCmsInterface::run will be called.
  pixels_per_thread | the maximum number of pixels that each call to JxlCmsInterface::run will have to transform.
  input_profile | the input colorspace for the transform.
  output_profile | the colorspace to which JxlCmsInterface::run should convert the input data.

  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: `intensity_target` cd/m² in PQ should map to and from (1, 1, 1) in the relative one.
  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 `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 `1.2 * 1.111^log2(intensity_target / 1000)` (footnote 2 page 8 of the same document).

Returns
  The data needed for the transform, or `NULL` in case of failure. This will be passed to the other functions as `user_data`.

## jpegxl_cms_run_func

typedef JXL_BOOL(* jpegxl_cms_run_func) (void *user_data, size_t thread, const float *input_buffer, float *output_buffer, size_t num_pixels)

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 `thread`, all between 0 (inclusive) and the value of `num_threads` passed to `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. `user_data` is the data returned by `init`. The buffers each contain `num_pixels` × `num_channels` interleaved floating point (0..1) samples where `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.

Parameters

  user_data | the data returned by `init`.
  thread | the index of the thread from which the function is being called.
  input_buffer | the buffer containing the pixel data to be transformed.
  output_buffer | the buffer receiving the transformed pixel data.
  num_pixels | the number of pixels to transform from `input` to `output`.

Returns
  JXL_TRUE on success, JXL_FALSE on failure.

## jpegxl_free_func

typedef void(* jpegxl_free_func) (void *opaque, void *address)

Deallocating function pointer type.

This function MUST do nothing if `address` is `NULL`.

Parameters

  opaque | custom memory manager handle provided by the caller.
  address | memory region pointer returned by jpegxl_alloc_func, or `NULL`.

## JxlBoxType

typedef char JxlBoxType[4]

Data type holding the 4-character type name of an ISOBMFF box.

## JxlMemoryManager

typedef struct JxlMemoryManagerStruct JxlMemoryManager

Memory Manager struct. These functions, when provided by the caller, will be used to handle memory allocations.

## JxlParallelRetCode

typedef int JxlParallelRetCode

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 `NULL` value of JxlParallelRunner will use an internal implementation without multi-threading. 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.

## JxlParallelRunFunction

typedef void(* JxlParallelRunFunction) (void *jpegxl_opaque, uint32_t value, size_t thread_id)

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 `value`. Calls for different value may be executed from different threads in parallel.

Parameters

  jpegxl_opaque | the `jpegxl_opaque` handle provided to JxlParallelRunner() must be passed here.
  value | the number in the range [start_range, end_range) of the call.
  thread_id | the thread number where this function is being called from. This must be lower than the `num_threads` value passed to JxlParallelRunInit.

## JxlParallelRunInit

typedef JxlParallelRetCode(* JxlParallelRunInit) (void *jpegxl_opaque, size_t num_threads)

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.

Parameters

  jpegxl_opaque | the `jpegxl_opaque` handle provided to JxlParallelRunner() must be passed here.
  num_threads | the maximum number of threads. This value must be positive.

Returns
  0 if the initialization process was successful.
  an error code if there was an error, which should be returned by JxlParallelRunner().

## JxlParallelRunner

typedef JxlParallelRetCode(* JxlParallelRunner) (void *runner_opaque, void *jpegxl_opaque, JxlParallelRunInit init, JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range)

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 `init` in the same thread that called it and then call the passed `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 `init` or `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.

Returns
  0 if the `init` call succeeded (returned 0) and no other error occurred in the runner code.
  JXL_PARALLEL_RET_RUNNER_ERROR if an error occurred in the runner code, for example, setting up the threads.
  the return value of `init()` if non-zero.

## Enumeration Type Documentation

## JxlBlendMode

enum JxlBlendMode

Frame blend modes. When decoding, if coalescing is enabled (default), this can be ignored.

## JxlColorSpace

enum JxlColorSpace

Color space of the image data.

Enumerator
JXL_COLOR_SPACE_RGB | Tristimulus RGB
JXL_COLOR_SPACE_GRAY | 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_XYB | XYB (opsin) color space
JXL_COLOR_SPACE_UNKNOWN | None of the other table entries describe the color space appropriately

## JxlDataType

enum JxlDataType

Data type for the sample values per channel per pixel.

Enumerator
JXL_TYPE_FLOAT | 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_UINT8 | Use type uint8_t. May clip wide color gamut data.
JXL_TYPE_UINT16 | Use type uint16_t. May clip wide color gamut data.
JXL_TYPE_FLOAT16 | Use 16-bit IEEE 754 half-precision floating point values

## JxlEndianness

enum JxlEndianness

Ordering of multi-byte data.

Enumerator
JXL_NATIVE_ENDIAN | 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_LITTLE_ENDIAN | Force little endian
JXL_BIG_ENDIAN | Force big endian

## JxlExtraChannelType

enum JxlExtraChannelType

Given type of an extra channel.

## JxlOrientation

enum JxlOrientation

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.

## JxlPrimaries

enum JxlPrimaries

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.

Enumerator
JXL_PRIMARIES_SRGB | 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_CUSTOM | 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_2100 | As specified in Rec. ITU-R BT.2100-1
JXL_PRIMARIES_P3 | As specified in SMPTE RP 431-2

## JxlProgressiveDetail

enum JxlProgressiveDetail

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)

## JxlRenderingIntent

enum JxlRenderingIntent

Renderig intent for color encoding, as specified in ISO 15076-1:2010

Enumerator
JXL_RENDERING_INTENT_PERCEPTUAL | vendor-specific
JXL_RENDERING_INTENT_RELATIVE | media-relative
JXL_RENDERING_INTENT_SATURATION | vendor-specific
JXL_RENDERING_INTENT_ABSOLUTE | ICC-absolute

## JxlTransferFunction

enum JxlTransferFunction

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.

Enumerator
JXL_TRANSFER_FUNCTION_709 | As specified in SMPTE RP 431-2
JXL_TRANSFER_FUNCTION_UNKNOWN | None of the other table entries describe the transfer function.
JXL_TRANSFER_FUNCTION_LINEAR | The gamma exponent is 1
JXL_TRANSFER_FUNCTION_SRGB | As specified in IEC 61966-2-1 sRGB
JXL_TRANSFER_FUNCTION_PQ | As specified in SMPTE ST 2084
JXL_TRANSFER_FUNCTION_DCI | As specified in SMPTE ST 428-1
JXL_TRANSFER_FUNCTION_HLG | As specified in Rec. ITU-R BT.2100-1 (HLG)
JXL_TRANSFER_FUNCTION_GAMMA | Transfer function follows power law given by the gamma value in JxlColorEncoding. Not a CICP value.

## JxlWhitePoint

enum JxlWhitePoint

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.

Enumerator
JXL_WHITE_POINT_D65 | CIE Standard Illuminant D65: 0.3127, 0.3290
JXL_WHITE_POINT_CUSTOM | 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_E | CIE Standard Illuminant E (equal-energy): 1/3, 1/3
JXL_WHITE_POINT_DCI | DCI-P3 from SMPTE RP 431-2: 0.314, 0.351