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 theinput
colorspace tooutput
, with up topixels_per_thread
pixels to transform per call to JxlCmsInterface::run.init_data
comes directly from the JxlCmsInterface instance. Sincerun
only receives the data returned byinit
, a reference toinit_data
should be kept there if access to it is desired inrun
. Likewise for JxlCmsInterface::destroy.The ICC data in
input
andoutput
is guaranteed to outlive theinit
/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 as1.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 asuser_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 ofnum_threads
passed toinit
(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 byinit
. The buffers each containnum_pixels
×num_channels
interleaved floating point (0..1) samples wherenum_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
tooutput
.- 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
isNULL
.- 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 passedfunc
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
orfunc
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
-
enumerator JXL_ORIENT_IDENTITY
-
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
-
enumerator JXL_CHANNEL_ALPHA
-
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
-
enumerator JXL_BLEND_REPLACE
-
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
-
enumerator JXL_COLOR_SPACE_RGB
-
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
-
enumerator JXL_WHITE_POINT_D65
-
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
-
enumerator JXL_PRIMARIES_SRGB
-
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.
-
enumerator JXL_TRANSFER_FUNCTION_709
-
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
-
enumerator JXL_RENDERING_INTENT_PERCEPTUAL
-
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
-
enumerator JXL_TYPE_FLOAT
-
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
-
enumerator JXL_NATIVE_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
-
enumerator JXL_BIT_DEPTH_FROM_PIXEL_FORMAT
-
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 JxlColorProfile::[anonymous] icc
-
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:
Public Members
-
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.
-
jpegxl_cms_init_func init
-
struct JxlPreviewHeader
- #include <codestream_header.h>
The codestream preview header
-
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
-
uint32_t tps_numerator
-
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
-
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 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.
-
uint8_t padding[100]
Padding for forwards-compatibility, in case more fields are exposed in a future version of the library.
-
JXL_BOOL have_container
-
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.
-
JxlExtraChannelType type
-
struct JxlHeaderExtensions
- #include <codestream_header.h>
Extensions in the codestream header.
Public Members
-
uint64_t extensions
Extension bits.
-
uint64_t extensions
-
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.
-
JxlBlendMode blendmode
-
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. When encoding, ID 3 is reserved to frames that are generated internally by the encoder, and should not be used by applications.
-
JXL_BOOL have_crop
-
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.
-
uint32_t duration
-
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.
-
JxlColorSpace color_space
-
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.
-
void *opaque
-
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): 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)
-
uint32_t num_channels
-
struct JxlBitDepth
- #include <types.h>
Data type for describing the interpretation of the input and output buffers in terms of the range of allowed input and output pixel values.
Public Members
-
JxlBitDepthType type
Bit depth setting, see comment on JxlBitDepthType
-
uint32_t bits_per_sample
Custom bits per sample
-
uint32_t exponent_bits_per_sample
Custom exponent bits per sample
-
JxlBitDepthType type
-
JXL_PARALLEL_RET_RUNNER_ERROR