LIBJXL
Loading...
Searching...
No Matches
Files | Classes | Typedefs | Enumerations
Color encoding and conversion
Collaboration diagram for Color encoding and conversion:

Files

file  cms_interface.h
 Interface to allow the injection of different color management systems (CMSes, also called color management modules, or CMMs) in JPEG XL.
 
file  color_encoding.h
 Color Encoding definitions used by JPEG XL. All CIE units are for the standard 1931 2 degree observer.
 

Classes

struct  JxlColorProfile
 
struct  JxlCmsInterface
 
struct  JxlColorEncoding
 

Typedefs

typedef JXL_BOOL(* jpegxl_cms_set_fields_from_icc_func) (void *user_data, const uint8_t *icc_data, size_t icc_size, JxlColorEncoding *c, JXL_BOOL *cmyk)
 
typedef void *(* jpegxl_cms_init_func) (void *init_data, size_t num_threads, size_t pixels_per_thread, const JxlColorProfile *input_profile, const JxlColorProfile *output_profile, float intensity_target)
 
typedef float *(* jpegxl_cms_get_buffer_func) (void *user_data, size_t thread)
 
typedef JXL_BOOL(* jpegxl_cms_run_func) (void *user_data, size_t thread, const float *input_buffer, float *output_buffer, size_t num_pixels)
 
typedef void(* jpegxl_cms_destroy_func) (void *)
 

Enumerations

enum  JxlColorSpace { JXL_COLOR_SPACE_RGB , JXL_COLOR_SPACE_GRAY , JXL_COLOR_SPACE_XYB , JXL_COLOR_SPACE_UNKNOWN }
 
enum  JxlWhitePoint { JXL_WHITE_POINT_D65 = 1 , JXL_WHITE_POINT_CUSTOM = 2 , JXL_WHITE_POINT_E = 10 , JXL_WHITE_POINT_DCI = 11 }
 
enum  JxlPrimaries { JXL_PRIMARIES_SRGB = 1 , JXL_PRIMARIES_CUSTOM = 2 , JXL_PRIMARIES_2100 = 9 , JXL_PRIMARIES_P3 = 11 }
 
enum  JxlTransferFunction {
  JXL_TRANSFER_FUNCTION_709 = 1 , JXL_TRANSFER_FUNCTION_UNKNOWN = 2 , JXL_TRANSFER_FUNCTION_LINEAR = 8 , JXL_TRANSFER_FUNCTION_SRGB = 13 ,
  JXL_TRANSFER_FUNCTION_PQ = 16 , JXL_TRANSFER_FUNCTION_DCI = 17 , JXL_TRANSFER_FUNCTION_HLG = 18 , JXL_TRANSFER_FUNCTION_GAMMA = 65535
}
 
enum  JxlRenderingIntent { JXL_RENDERING_INTENT_PERCEPTUAL = 0 , JXL_RENDERING_INTENT_RELATIVE , JXL_RENDERING_INTENT_SATURATION , JXL_RENDERING_INTENT_ABSOLUTE }
 

Detailed Description

Typedef Documentation

◆ jpegxl_cms_destroy_func

typedef void(* jpegxl_cms_destroy_func) (void *)

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

◆ jpegxl_cms_get_buffer_func

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

Returns a buffer that can be used by callers of the interface to store the input of the conversion or read its result, if they pass it as the input or output of the run function.

Parameters
user_datathe data returned by init.
threadthe index of the thread for which to return a buffer.
Returns
A buffer that can be used by the caller for passing to run.

◆ jpegxl_cms_init_func

typedef void *(* jpegxl_cms_init_func) (void *init_data, size_t num_threads, size_t pixels_per_thread, const JxlColorProfile *input_profile, const JxlColorProfile *output_profile, float intensity_target)

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

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

Parameters
init_dataJxlCmsInterface::init_data passed as-is.
num_threadsthe maximum number of threads from which JxlCmsInterface::run will be called.
pixels_per_threadthe maximum number of pixels that each call to JxlCmsInterface::run will have to transform.
input_profilethe input colorspace for the transform.
output_profilethe colorspace to which JxlCmsInterface::run should convert the input data.
intensity_targetfor colorspaces where luminance is relative (essentially: not PQ), indicates the luminance at which (1, 1, 1) will be displayed. This is useful for conversions between PQ and a relative luminance colorspace, in either direction: intensity_target cd/m² in PQ should map to and from (1, 1, 1) in the relative one.
It is also used for conversions to and from HLG, as it is scene-referred while other colorspaces are assumed to be display-referred. That is, conversions from HLG should apply the OOTF for a peak display luminance of intensity_target, and conversions to HLG should undo it. The OOTF is a gamma function applied to the luminance channel (https://www.itu.int/rec/R-REC-BT.2100-2-201807-I page 7), with the gamma value computed as 1.2 * 1.111^log2(intensity_target / 1000) (footnote 2 page 8 of the same document).
Returns
The data needed for the transform, or NULL in case of failure. This will be passed to the other functions as user_data.

◆ jpegxl_cms_run_func

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

Executes one transform and returns true on success or false on error. It must be possible to call this from different threads with different values for thread, all between 0 (inclusive) and the value of num_threads passed to init (exclusive). It is allowed to implement this by locking such that the transforms are essentially performed sequentially, if such a performance profile is acceptable. user_data is the data returned by init. The buffers each contain num_pixels × num_channels interleaved floating point (0..1) samples where num_channels is the number of color channels of their respective color profiles. It is guaranteed that the only case in which they might overlap is if the output has fewer channels than the input, in which case the pointers may be identical. For CMYK data, 0 represents the maximum amount of ink while 1 represents no ink.

Parameters
user_datathe data returned by init.
threadthe index of the thread from which the function is being called.
input_bufferthe buffer containing the pixel data to be transformed.
output_bufferthe buffer receiving the transformed pixel data.
num_pixelsthe number of pixels to transform from input to output.
Returns
JXL_TRUE on success, JXL_FALSE on failure.

◆ jpegxl_cms_set_fields_from_icc_func

typedef JXL_BOOL(* jpegxl_cms_set_fields_from_icc_func) (void *user_data, const uint8_t *icc_data, size_t icc_size, JxlColorEncoding *c, JXL_BOOL *cmyk)

Parses an ICC profile and populates c and cmyk with the data.

Parameters
user_dataJxlCmsInterface::set_fields_data passed as-is.
icc_datathe ICC data to parse.
icc_sizehow many bytes of icc_data are valid.
ca JxlColorEncoding to populate if applicable.
cmyka boolean to set to whether the colorspace is a CMYK colorspace.
Returns
Whether the relevant fields in c were successfully populated.

Enumeration Type Documentation

◆ JxlColorSpace

Color space of the image data.

Enumerator
JXL_COLOR_SPACE_RGB 

Tristimulus RGB

JXL_COLOR_SPACE_GRAY 

Luminance based, the primaries in JxlColorEncoding must be ignored. This value implies that num_color_channels in JxlBasicInfo is 1, any other value implies num_color_channels is 3.

JXL_COLOR_SPACE_XYB 

XYB (opsin) color space

JXL_COLOR_SPACE_UNKNOWN 

None of the other table entries describe the color space appropriately

◆ JxlPrimaries

Built-in primaries for color encoding. When decoding, the primaries can be read from the JxlColorEncoding primaries_red_xy, primaries_green_xy and primaries_blue_xy fields regardless of the enum value. When encoding, the enum values except JXL_PRIMARIES_CUSTOM override the numerical fields. Some enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)), however the white point and RGB primaries are separate enums here.

Enumerator
JXL_PRIMARIES_SRGB 

The CIE xy values of the red, green and blue primaries are: 0.639998686, 0.330010138; 0.300003784, 0.600003357; 0.150002046, 0.059997204

JXL_PRIMARIES_CUSTOM 

Primaries must be read from the JxlColorEncoding primaries_red_xy, primaries_green_xy and primaries_blue_xy fields, or as ICC profile. This enum value is not an exact match of the corresponding CICP value.

JXL_PRIMARIES_2100 

As specified in Rec. ITU-R BT.2100-1

JXL_PRIMARIES_P3 

As specified in SMPTE RP 431-2

◆ JxlRenderingIntent

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

Enumerator
JXL_RENDERING_INTENT_PERCEPTUAL 

vendor-specific

JXL_RENDERING_INTENT_RELATIVE 

media-relative

JXL_RENDERING_INTENT_SATURATION 

vendor-specific

JXL_RENDERING_INTENT_ABSOLUTE 

ICC-absolute

◆ JxlTransferFunction

Built-in transfer functions for color encoding. Enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)) unless specified otherwise.

Enumerator
JXL_TRANSFER_FUNCTION_709 

As specified in ITU-R BT.709-6

JXL_TRANSFER_FUNCTION_UNKNOWN 

None of the other table entries describe the transfer function.

JXL_TRANSFER_FUNCTION_LINEAR 

The gamma exponent is 1

JXL_TRANSFER_FUNCTION_SRGB 

As specified in IEC 61966-2-1 sRGB

JXL_TRANSFER_FUNCTION_PQ 

As specified in SMPTE ST 2084

JXL_TRANSFER_FUNCTION_DCI 

As specified in SMPTE ST 428-1

JXL_TRANSFER_FUNCTION_HLG 

As specified in Rec. ITU-R BT.2100-1 (HLG)

JXL_TRANSFER_FUNCTION_GAMMA 

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

◆ JxlWhitePoint

Built-in white points for color encoding. When decoding, the numerical xy white point value can be read from the JxlColorEncoding white_point field regardless of the enum value. When encoding, enum values except JXL_WHITE_POINT_CUSTOM override the numerical fields. Some enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)), however the white point and RGB primaries are separate enums here.

Enumerator
JXL_WHITE_POINT_D65 

CIE Standard Illuminant D65: 0.3127, 0.3290

JXL_WHITE_POINT_CUSTOM 

White point must be read from the JxlColorEncoding white_point field, or as ICC profile. This enum value is not an exact match of the corresponding CICP value.

JXL_WHITE_POINT_E 

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

JXL_WHITE_POINT_DCI 

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