Common API concepts

group libjxl_common

Defines

JXL_PARALLEL_RET_RUNNER_ERROR: General error returned by the JxlParallelRunInit function to indicate an error.

JXL_BOOL

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_TRUE: Portable true replacement.

JXL_FALSE: Portable false replacement.

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

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.

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

Return:

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

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.

Param user_data:: the data returned by 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 run.

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.

Param user_data:: the data returned by 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 input to output.
Return:: JXL_TRUE on success, JXL_FALSE on failure.

typedef void (*jpegxl_cms_destroy_func)(void*): Performs the necessary clean-up and frees the memory allocated for user data.

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.

Param opaque:: custom memory manager handle provided by the caller.
Param size:: in bytes of the requested memory region.
Return:: NULL if the memory can not be allocated,
Return:: pointer to the memory otherwise.

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

Deallocating function pointer type.

This function MUST do nothing if address is NULL.

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

typedef struct JxlMemoryManagerStruct JxlMemoryManager: Memory Manager struct. These functions, when provided by the caller, will be used to handle memory allocations.

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.

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.

Param jpegxl_opaque:: the 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 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.

Param jpegxl_opaque:: the 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 num_threads value passed to JxlParallelRunInit.

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.

Return:: 0 if the 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 init() if non-zero.

typedef char JxlBoxType[4]: Data type holding the 4-character type name of an ISOBMFF box.

Enums

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.

Values:

enumerator JXL_ORIENT_IDENTITY

enumerator JXL_ORIENT_FLIP_HORIZONTAL

enumerator JXL_ORIENT_ROTATE_180

enumerator JXL_ORIENT_FLIP_VERTICAL

enumerator JXL_ORIENT_TRANSPOSE

enumerator JXL_ORIENT_ROTATE_90_CW

enumerator JXL_ORIENT_ANTI_TRANSPOSE

enumerator JXL_ORIENT_ROTATE_90_CCW

enum JxlExtraChannelType

Given type of an extra channel.

Values:

enumerator JXL_CHANNEL_ALPHA

enumerator JXL_CHANNEL_DEPTH

enumerator JXL_CHANNEL_SPOT_COLOR

enumerator JXL_CHANNEL_SELECTION_MASK

enumerator JXL_CHANNEL_BLACK

enumerator JXL_CHANNEL_CFA

enumerator JXL_CHANNEL_THERMAL

enumerator JXL_CHANNEL_RESERVED0

enumerator JXL_CHANNEL_RESERVED1

enumerator JXL_CHANNEL_RESERVED2

enumerator JXL_CHANNEL_RESERVED3

enumerator JXL_CHANNEL_RESERVED4

enumerator JXL_CHANNEL_RESERVED5

enumerator JXL_CHANNEL_RESERVED6

enumerator JXL_CHANNEL_RESERVED7

enumerator JXL_CHANNEL_UNKNOWN

enumerator JXL_CHANNEL_OPTIONAL

enum JxlBlendMode

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

Values:

enumerator JXL_BLEND_REPLACE

enumerator JXL_BLEND_ADD

enumerator JXL_BLEND_BLEND

enumerator JXL_BLEND_MULADD

enumerator JXL_BLEND_MUL

enum JxlColorSpace

Color space of the image data.

Values:

enumerator JXL_COLOR_SPACE_RGB: Tristimulus RGB

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

enumerator JXL_COLOR_SPACE_XYB: XYB (opsin) color space

enumerator JXL_COLOR_SPACE_UNKNOWN: None of the other table entries describe the color space appropriately

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.

Values:

enumerator JXL_WHITE_POINT_D65: CIE Standard Illuminant D65: 0.3127, 0.3290

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

enumerator JXL_WHITE_POINT_E: CIE Standard Illuminant E (equal-energy): 1/3, 1/3

enumerator JXL_WHITE_POINT_DCI: DCI-P3 from SMPTE RP 431-2: 0.314, 0.351

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.

Values:

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

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

enumerator JXL_PRIMARIES_2100: As specified in Rec. ITU-R BT.2100-1

enumerator JXL_PRIMARIES_P3: As specified in SMPTE RP 431-2

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.

Values:

enumerator JXL_TRANSFER_FUNCTION_709: As specified in SMPTE RP 431-2

enumerator JXL_TRANSFER_FUNCTION_UNKNOWN: None of the other table entries describe the transfer function.

enumerator JXL_TRANSFER_FUNCTION_LINEAR: The gamma exponent is 1

enumerator JXL_TRANSFER_FUNCTION_SRGB: As specified in IEC 61966-2-1 sRGB

enumerator JXL_TRANSFER_FUNCTION_PQ: As specified in SMPTE ST 2084

enumerator JXL_TRANSFER_FUNCTION_DCI: As specified in SMPTE ST 428-1

enumerator JXL_TRANSFER_FUNCTION_HLG: As specified in Rec. ITU-R BT.2100-1 (HLG)

enumerator JXL_TRANSFER_FUNCTION_GAMMA: Transfer function follows power law given by the gamma value in JxlColorEncoding. Not a CICP value.

enum JxlRenderingIntent

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

Values:

enumerator JXL_RENDERING_INTENT_PERCEPTUAL: vendor-specific

enumerator JXL_RENDERING_INTENT_RELATIVE: media-relative

enumerator JXL_RENDERING_INTENT_SATURATION: vendor-specific

enumerator JXL_RENDERING_INTENT_ABSOLUTE: ICC-absolute

enum JxlDataType

Data type for the sample values per channel per pixel.

Values:

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.

enumerator JXL_TYPE_UINT8: Use type uint8_t. May clip wide color gamut data.

enumerator JXL_TYPE_UINT16: Use type uint16_t. May clip wide color gamut data.

enumerator JXL_TYPE_FLOAT16: Use 16-bit IEEE 754 half-precision floating point values

enum JxlEndianness

Ordering of multi-byte data.

Values:

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.

enumerator JXL_LITTLE_ENDIAN: Force little endian

enumerator JXL_BIG_ENDIAN: Force big endian

enum JxlBitDepthType

Settings for the interpretation of the input and output buffers.

Values:

enumerator JXL_BIT_DEPTH_FROM_PIXEL_FORMAT: 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).

enumerator JXL_BIT_DEPTH_FROM_CODESTREAM: 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.

enumerator JXL_BIT_DEPTH_CUSTOM: This setting can only be used in the decoder to select a custom range for pixel output

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)

Values:

enumerator kFrames

enumerator kDC

enumerator kLastPasses

enumerator kPasses

enumerator kDCProgressive

enumerator kDCGroups

enumerator kGroups

Variables

JXL_DEPRECATED static const int JXL_TYPE_BOOLEAN = 1

JXL_DEPRECATED static const int JXL_TYPE_UINT32 = 4

struct JxlColorProfile

#include <cms_interface.h>

Represents an input or output colorspace to a color transform, as a serialized ICC profile.

Public Members

struct JxlColorProfile::[anonymous] icc: The serialized ICC profile. This is guaranteed to be present and valid.

JxlColorEncoding color_encoding: 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.

size_t num_channels: Number of components per pixel. This can be deduced from the other representations of the colorspace but is provided for convenience and validation.

struct JxlCmsInterface

#include <cms_interface.h>

Interface for performing colorspace transforms. The 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:

$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)" }$

Public Members

void *init_data: CMS-specific data that will be passed to init.

jpegxl_cms_init_func init: Prepares a colorspace transform as described in the documentation of jpegxl_cms_init_func.

jpegxl_cms_get_buffer_func get_src_buf: Returns a buffer that can be used as input to run.

jpegxl_cms_get_buffer_func get_dst_buf: Returns a buffer that can be used as output from run.

jpegxl_cms_run_func run: Executes the transform on a batch of pixels, per jpegxl_cms_run_func.

jpegxl_cms_destroy_func destroy: Cleans up the transform.

struct JxlPreviewHeader

#include <codestream_header.h>

The codestream preview header

Public Members

uint32_t xsize: Preview width in pixels

uint32_t ysize: Preview height in pixels

struct JxlAnimationHeader

#include <codestream_header.h>

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.

Public Members

uint32_t tps_numerator: Numerator of ticks per second of a single animation frame time unit

uint32_t tps_denominator: Denominator of ticks per second of a single animation frame time unit

uint32_t num_loops: Amount of animation loops, or 0 to repeat infinitely

JXL_BOOL have_timecodes: Whether animation time codes are present at animation frames in the codestream

struct JxlBasicInfo

#include <codestream_header.h>

Basic image information. This information is available from the file signature and first part of the codestream header.

Public Members

JXL_BOOL have_container: Whether the codestream is embedded in the container format. If true, metadata information and extensions may be available in addition to the codestream.

uint32_t xsize: Width of the image in pixels, before applying orientation.

uint32_t ysize: Height of the image in pixels, before applying orientation.

uint32_t bits_per_sample: Original image color channel bit depth.

uint32_t exponent_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.

float intensity_target: 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 min_nits: 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.

JXL_BOOL relative_to_max_display

See the description of