Color encoding and conversion
- group libjxl_color
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)
Parses an ICC profile and populates
candcmykwith the data.- Param user_data:
JxlCmsInterface::set_fields_data passed as-is.
- Param icc_data:
the ICC data to parse.
- Param icc_size:
how many bytes of icc_data are valid.
- Param c:
a JxlColorEncoding to populate if applicable.
- Param cmyk:
a boolean to set to whether the colorspace is a CMYK colorspace.
- Return:
Whether the relevant fields in
cwere successfully populated.
-
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_threadsparallel transforms from theinputcolorspace tooutput, with up topixels_per_threadpixels to transform per call to JxlCmsInterface::run.init_datacomes directly from the JxlCmsInterface instance. Sincerunonly receives the data returned byinit, a reference toinit_datashould be kept there if access to it is desired inrun. Likewise for JxlCmsInterface::destroy.The ICC data in
inputandoutputis guaranteed to outlive theinit/run/destroycycle.- 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_targetcd/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
NULLin 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
runfunction.- 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_threadspassed 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_datais the data returned byinit. The buffers each containnum_pixels×num_channelsinterleaved floating point (0..1) samples wherenum_channelsis 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
inputtooutput.- Return:
-
typedef void (*jpegxl_cms_destroy_func)(void*)
Performs the necessary clean-up and frees the memory allocated for user data.
Enums
-
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
-
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
initfunction 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)"
}](_images/graphviz-f063e92df1a0cb78de5cf5871677ada82e9a18aa.png)
Public Members
-
void *set_fields_data
CMS-specific data that will be passed to set_fields_from_icc.
-
jpegxl_cms_set_fields_from_icc_func set_fields_from_icc
Populates a JxlColorEncoding from an ICC profile.
-
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.
-
void *set_fields_data
-
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
-
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)