gamut_map.h

Go to the documentation of this file.

#pragma once
 
// Gamut mapping onto the device hull (P7, #4041).
//
// `docs/color-gamut-algorithm-selection.md` selects OKLCh chroma compression
// and rules out the cheaper alternatives: clipping and max-normalization
// both land about 20 dE2000 from the reference against a budget of 0.5, and
// no amount of clamping substitutes for the objective.
//
// The per-pixel path here is fully bounded and contains no iterative solver
// in the A3/B11 sense, no division, no float, and no trigonometry:
//
//   1. one forward OKLab transform (three cube roots),
//   2. one comparison against a precomputed device constant for lightness,
//   3. eight halvings, each an inverse OKLab transform and one solve.
//
// Chroma is compressed by scaling (a, b) toward zero rather than by going
// polar. Since a = C cos h and b = C sin h, scaling both by one factor is
// exactly scaling C at fixed hue -- so hue is preserved by construction and
// atan2, hypot, cos and sin never appear.
 
#include "fl/gfx/device_solve.h"
#include "fl/gfx/white_allocation.h"
#include "fl/stl/int.h"
#include "fl/stl/noexcept.h"
 
namespace fl {

constexpr int kGamutMapHalvings = 8;

struct GamutMapQ16 {
    EmitterSolveMatrixQ16 solve;

    i32 max_neutral_lightness;
};

struct GamutMapRgbwQ16 {
    WhiteAllocationQ16 allocation;

    i32 max_neutral_lightness;
};

bool buildGamutMapRgbwQ16(const colorimetric_response::EmitterProfile& profile,
                          const i32 (&white_xyz)[3],
                          WhiteAllocationPolicy policy,
                          GamutMapRgbwQ16* out) FL_NO_EXCEPT;

bool buildGamutMapRgbwFromSolveQ16(
    const colorimetric_response::EmitterProfile& profile,
    const EmitterSolveMatrixQ16& solve, const i32 (&white_xyz)[3],
    WhiteAllocationPolicy policy, GamutMapRgbwQ16* out) FL_NO_EXCEPT;

void mapAndAllocateRgbwQ16(const GamutMapRgbwQ16& map, const i32 (&xyz)[3],
                           i32 (&drives)[4]) FL_NO_EXCEPT;

struct GamutMapRgbwwQ16 {
    TwoWhiteAllocationQ16 allocation;

    i32 max_neutral_lightness;
};

bool buildGamutMapRgbwwQ16(const colorimetric_response::EmitterProfile& profile,
                           const i32 (&white1_xyz)[3],
                           const i32 (&white2_xyz)[3],
                           WhiteAllocationPolicy policy,
                           GamutMapRgbwwQ16* out) FL_NO_EXCEPT;

bool buildGamutMapRgbwwFromSolveQ16(
    const colorimetric_response::EmitterProfile& profile,
    const EmitterSolveMatrixQ16& solve, const i32 (&white1_xyz)[3],
    const i32 (&white2_xyz)[3], WhiteAllocationPolicy policy,
    GamutMapRgbwwQ16* out) FL_NO_EXCEPT;

void mapAndAllocateRgbwwQ16(const GamutMapRgbwwQ16& map, const i32 (&xyz)[3],
                            i32 (&drives)[5]) FL_NO_EXCEPT;

bool buildGamutMapQ16(const colorimetric_response::EmitterProfile& profile, GamutMapQ16* out) FL_NO_EXCEPT;

bool buildGamutMapFromSolveQ16(const EmitterSolveMatrixQ16& solve,
                              GamutMapQ16* out) FL_NO_EXCEPT;

void mapAndSolveDrivesQ16(const GamutMapQ16& map, const i32 (&xyz)[3],
                          i32 (&drives)[3]) FL_NO_EXCEPT;
 
}  // namespace fl