JxlDecoderGetColorAsEncodedProfile

jpegxl_sys::decode

Function JxlDecoderGetColorAsEncodedProfile 

Source 
pub unsafe extern "C-unwind" fn JxlDecoderGetColorAsEncodedProfile(
    dec: *const JxlDecoder,
    target: JxlColorProfileTarget,
    color_encoding: *mut JxlColorEncoding,
) -> JxlDecoderStatus
Expand description

Outputs the color profile as JPEG XL encoded structured data, if available. This is an alternative to an ICC Profile, which can represent a more limited amount of color spaces, but represents them exactly through enum values.

It is often possible to use JxlDecoderGetColorAsICCProfile as an alternative anyway. The following scenarios are possible:

  • The JPEG XL image has an attached ICC Profile, in that case, the encoded structured data is not available and this function will return an error status. JxlDecoderGetColorAsICCProfile should be called instead.
  • The JPEG XL image has an encoded structured color profile, and it represents an RGB or grayscale color space. This function will return it. You can still use JxlDecoderGetColorAsICCProfile as well as an alternative if desired, though depending on which RGB color space is represented, the ICC profile may be a close approximation. It is also not always feasible to deduce from an ICC profile which named color space it exactly represents, if any, as it can represent any arbitrary space. HDR color spaces such as those using PQ and HLG are also potentially problematic, in that: while ICC profiles can encode a transfer function that happens to approximate those of PQ and HLG (HLG for only one given system gamma at a time, and necessitating a 3D LUT if gamma is to be different from 1), they cannot (before ICCv4.4) semantically signal that this is the color space that they represent. Therefore, they will typically not actually be interpreted as representing an HDR color space. This is especially detrimental to PQ which will then be interpreted as if the maximum signal value represented SDR white instead of 10000 cd/m^2, meaning that the image will be displayed two orders of magnitude (5-7 EV) too dim.
  • The JPEG XL image has an encoded structured color profile, and it indicates an unknown or xyb color space. In that case, JxlDecoderGetColorAsICCProfile is not available.

When rendering an image on a system where ICC-based color management is used, JxlDecoderGetColorAsICCProfile should generally be used first as it will return a ready-to-use profile (with the aforementioned caveat about HDR). When knowledge about the nominal color space is desired if available, JxlDecoderGetColorAsEncodedProfile should be used first.

§Parameters

  • dec: decoder object
  • target: whether to get the original color profile from the metadata or the color profile of the decoded pixels.
  • color_encoding: struct to copy the information into, or NULL to only check whether the information is available through the return value.

§Returns