white_allocation.h

Go to the documentation of this file.

#pragma once
 
// White-preferred allocation for a device with a white emitter (C3, #4041).
//
// A white emitter makes the emitter matrix wide: a target's preimage is no
// longer unique, and C3 asks for the white-preferred one -- as much light
// from the white emitter as the target allows.
//
// The P5 reference finds it by enumerating vertices, which A3/B11 forbid per
// pixel. It does not need to be. With the white emitter at drive w, the RGB
// drives making up the difference are
//
//     d(w) = M^-1 . target  -  w * (M^-1 . white)
//
// which is affine in w. Each of the six bounds on the three RGB drives is
// therefore one inequality in w, the feasible set is a single interval, and
// white-preferred is its upper end.
//
// `docs/color-gamut-algorithm-selection.md` records the measurement: over
// the corpus's `rgbw` and `non_d65_white` devices this reproduces the
// reference's drives to 1.1e-15 and 7.8e-16 respectively -- float64
// rounding. The derivation never assumed the white sat on the neutral axis,
// which is what the second device checks.
//
// Two whites are a different problem, solved by
// `allocateTwoWhiteDrivesQ16` further down: maximizing w1 + w2 is a linear
// program over a polygon, and the obvious reduction -- run this twice and
// keep the better answer -- agrees with the reference on every corpus vector
// while being wrong on 85% of random reachable targets, because a single
// emitter's drive is capped at 1. See the same document.
 
#include "fl/gfx/device_solve.h"
#include "fl/stl/int.h"
#include "fl/stl/noexcept.h"
 
namespace fl {

enum class WhiteAllocationPolicy {
    WhitePreferred,

    RgbPreferred,
};

struct WhiteAllocationQ16 {
    EmitterSolveMatrixQ16 rgb_solve;

    i32 per_white[3];

    i32 slack[3];

    WhiteAllocationPolicy policy;
};

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

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

bool allocateEmitterDrivesQ16(const WhiteAllocationQ16& allocation,
                              const i32 (&xyz)[3],
                              i32 (&drives)[4]) FL_NO_EXCEPT;

struct TwoWhiteAllocationQ16 {
    EmitterSolveMatrixQ16 rgb_solve;

    i32 per_white2[3];

    i32 difference[3];

    WhiteAllocationPolicy policy;
};

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

bool buildTwoWhiteAllocationFromSolveQ16(
    const EmitterSolveMatrixQ16& solve, const i32 (&white1_xyz)[3],
    const i32 (&white2_xyz)[3], WhiteAllocationPolicy policy,
    TwoWhiteAllocationQ16* out) FL_NO_EXCEPT;

bool allocateTwoWhiteDrivesQ16(const TwoWhiteAllocationQ16& allocation,
                               const i32 (&xyz)[3],
                               i32 (&drives)[5]) FL_NO_EXCEPT;
 
}  // namespace fl