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 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 JxlIntrinsicSizeHeader
#include <codestream_header.h>

The intrinsic size header

Public Members

uint32_t xsize

Intrinsic width in pixels

uint32_t ysize

Intrinsic 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

See also

linear_below.

float linear_below

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

JXL_BOOL uses_original_profile

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

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_animation

Indicates animation frames exist in the codestream. The animation information is not included in the basic info.

JxlOrientation orientation

Image orientation, value 1-8 matching the values used by JEITA CP-3451C (Exif version 2.3).

uint32_t num_color_channels

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_extra_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 alpha_bits

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

JXL_BOOL alpha_premultiplied

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.

JxlPreviewHeader preview

Dimensions of encoded preview image, only used if have_preview is JXL_TRUE.

JxlAnimationHeader animation

Animation header with global animation properties for all frames, only used if have_animation is JXL_TRUE.

uint32_t intrinsic_xsize

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_ysize

Intrinsic heigth 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.

uint8_t padding[100]

Padding for forwards-compatibility, in case more fields are exposed in a future version of the library.

struct JxlExtraChannelInfo
#include <codestream_header.h>

Information for a single extra channel.

Public Members

JxlExtraChannelType type

Given type of an extra channel.

uint32_t bits_per_sample

Total bits per sample for this channel.

uint32_t exponent_bits_per_sample

Floating point exponent bits per channel, or 0 if they are unsigned integer.

uint32_t dim_shift

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 name_length

Length of the extra channel name in bytes, or 0 if no name. Excludes null termination character.

JXL_BOOL alpha_premultiplied

Whether alpha channel uses premultiplied alpha. Only applicable if type is JXL_CHANNEL_ALPHA.

float spot_color[4]

Spot color of the current spot channel in linear RGBA. Only applicable if type is JXL_CHANNEL_SPOT_COLOR.

uint32_t cfa_channel

Only applicable if type is JXL_CHANNEL_CFA. TODO(lode): add comment about the meaning of this field.

struct JxlHeaderExtensions
#include <codestream_header.h>

Extensions in the codestream header.

Public Members

uint64_t extensions

Extension bits.

struct JxlBlendInfo
#include <codestream_header.h>

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.

Public Members

JxlBlendMode blendmode

Blend mode.

uint32_t source

Reference frame ID to use as the ‘bottom’ layer (0-3).

uint32_t alpha

Which extra channel to use as the ‘alpha’ channel for blend modes JXL_BLEND_BLEND and JXL_BLEND_MULADD.

JXL_BOOL clamp

Clamp values to [0,1] for the purpose of blending.

struct JxlLayerInfo
#include <codestream_header.h>

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.

Public Members

JXL_BOOL have_crop

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.

int32_t crop_x0

Horizontal offset of the frame (can be negative).

int32_t crop_y0

Vertical offset of the frame (can be negative).

uint32_t xsize

Width of the frame (number of columns).

uint32_t ysize

Height of the frame (number of rows).

JxlBlendInfo blend_info

The blending info for the color channels. Blending info for extra channels has to be retrieved separately using JxlDecoderGetExtraChannelBlendInfo.

uint32_t save_as_reference

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.

struct JxlFrameHeader
#include <codestream_header.h>

The header of one displayed frame or non-coalesced layer.

Public Members

uint32_t duration

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 timecode

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 name_length

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 JxlEncoderSetFrameName is used instead to set the name and the length.

JXL_BOOL is_last

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, JxlEncoderCloseFrames is used to indicate the last frame to the encoder instead.

JxlLayerInfo layer_info

Information about the layer in case of no coalescing.

struct JxlColorEncoding
#include <color_encoding.h>

Color encoding of the image as structured information.

Public Members

JxlColorSpace color_space

Color space of the image data.

JxlWhitePoint white_point

Built-in white point. If this value is JXL_WHITE_POINT_CUSTOM, must use the numerical whitepoint values from white_point_xy.

double white_point_xy[2]

Numerical whitepoint values in CIE xy space.

JxlPrimaries primaries

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.

double primaries_red_xy[2]

Numerical red primary values in CIE xy space.

double primaries_green_xy[2]

Numerical green primary values in CIE xy space.

double primaries_blue_xy[2]

Numerical blue primary values in CIE xy space.

JxlTransferFunction transfer_function

Transfer function if have_gamma is 0

double gamma

Gamma value used when transfer_function is JXL_TRANSFER_FUNCTION_GAMMA

JxlRenderingIntent rendering_intent

Rendering intent defined for the color profile.

struct JxlMemoryManagerStruct
#include <memory_manager.h>

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

Public Members

void *opaque

The opaque pointer that will be passed as the first parameter to all the functions in this struct.

jpegxl_alloc_func alloc

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_free_func free

Free function matching the alloc() member.

struct JxlPixelFormat
#include <types.h>

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): implement padding / alignment (row stride) TODO(lode): support different channel orders if needed (RGB, BGR, …)

Public Members

uint32_t num_channels

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.

JxlDataType data_type

Data type of each channel.

JxlEndianness endianness

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.

size_t align

Align scanlines to a multiple of align bytes, or 0 to require no alignment at all (which has the same effect as value 1)