buildGamutMapRgbwFromSolveQ16()

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

Bind a four-emitter map from an effective RGB solve and a white column already adapted into the same D65 working coordinates.

Definition at line 434 of file gamut_map.cpp.hpp.

                                                                     {
    if (out == nullptr) {
        return false;
    }
    if (!buildWhiteAllocationFromSolveQ16(profile, solve, white_xyz, policy,
                                          &out->allocation)) {
        return false;
    }
 
    i32 neutral_drives[3];
    solveRgbDrivesQ16(out->allocation.rgb_solve, kGamutD65Q16, neutral_drives);
    for (int i = 0; i < 3; ++i) {
        // As in the three-emitter build: every drive, not just the largest.
        if (neutral_drives[i] <= 0) {
            return false;
        }
    }
 
    // The three-emitter bound, reached with the white emitter off. Whatever
    // else happens this neutral is attainable: at 1 / max(d0) the RGB drives
    // are exactly in [0, 1] with no white at all.
    i32 largest_neutral_drive = neutral_drives[0];
    for (int i = 1; i < 3; ++i) {
        if (neutral_drives[i] > largest_neutral_drive) {
            largest_neutral_drive = neutral_drives[i];
        }
    }
    i64 reachable = (static_cast<i64>(kGamutFullDrive) << 16) /
                    static_cast<i64>(largest_neutral_drive);
 
    // Clamped for the same reason the three-emitter build clamps it, and to
    // the same place: `buildRgbSolveMatrixQ16` accepts emitter luminances up
    // to 1e6, so a profile bright enough to reach D65 on one or two raw
    // units of drive puts `2^32 / largest` at or past i32's range -- exactly
    // 2^31 at largest == 2. `optimistic` starts at `kOklabQ16MaxMagnitude`,
    // so for such a profile the bisection below is skipped and the narrowing
    // is reached directly. 64.0 is where the OKLab transform's domain ends,
    // so nothing downstream can tell the difference.
    if (reachable > kOklabQ16MaxMagnitude) {
        reachable = kOklabQ16MaxMagnitude;
    }
 
    // An upper bound on what the white emitter can add. Along the D65 ray
    // the RGB drives are s * d0 - w * dW, so the *upper* limit on drive i is
    // loosest at w = 1 when dW_i is positive and at w = 0 when it is
    // negative -- hence max(dW_i, 0). Dropping the lower limits, and letting
    // each channel pick its own w, are both relaxations, so this is an upper
    // bound and never an under-estimate.
    i64 optimistic = static_cast<i64>(kOklabQ16MaxMagnitude);
    for (int i = 0; i < 3; ++i) {
        const i32 per_white = out->allocation.per_white[i];
        const i64 numerator = static_cast<i64>(kGamutFullDrive) +
                              (per_white > 0 ? static_cast<i64>(per_white) : 0);
        const i64 candidate =
            (numerator << 16) / static_cast<i64>(neutral_drives[i]);
        if (candidate < optimistic) {
            optimistic = candidate;
        }
    }
 
    // That upper bound is not generally attainable, and treating it as if it
    // were is a real bug rather than a theoretical one: it enforces only the
    // upper limits on the RGB drives, and full white can push a *different*
    // channel negative. With dW = (0.9, 0.05, 0.05) against
    // d0 = (0.21, 0.72, 0.07) the formula gives 1.468, where the red drive
    // works out at 1.468 * 0.21 - 0.9 = -0.59. Storing that would leave the
    // mapper with a zero-chroma candidate its own halving search cannot
    // satisfy, and the fallback would then return four zero drives for a
    // colour that is not black.
    //
    // So the bound is bisected between the two at bind time. This is not an
    // iterative solver in the A3/B11 sense: it runs once per profile, never
    // per pixel, and the per-pixel path sees only the stored result.
    if (optimistic > reachable) {
        i64 low = reachable;
        i64 high = optimistic;
        for (int step = 0; step < 24; ++step) {
            const i64 middle = (low + high) / 2;
            const i32 trial_scale = static_cast<i32>(middle);
            const i32 trial[3] = {
                scaleGamutQ16(kGamutD65Q16[0], trial_scale),
                scaleGamutQ16(kGamutD65Q16[1], trial_scale),
                scaleGamutQ16(kGamutD65Q16[2], trial_scale),
            };
            i32 trial_drives[4];
            if (allocateEmitterDrivesQ16(out->allocation, trial, trial_drives)) {
                low = middle;
            } else {
                high = middle;
            }
        }
        reachable = low;
    }
 
    const i32 scale = static_cast<i32>(reachable);
    const i32 brightest_neutral[3] = {
        scaleGamutQ16(kGamutD65Q16[0], scale),
        scaleGamutQ16(kGamutD65Q16[1], scale),
        scaleGamutQ16(kGamutD65Q16[2], scale),
    };
    i32 lab[3];
    xyzToOklabQ16(brightest_neutral, lab);
    out->max_neutral_lightness = lab[0];
    return true;
}

References allocateEmitterDrivesQ16(), buildWhiteAllocationFromSolveQ16(), FL_NO_EXCEPT, kOklabQ16MaxMagnitude, scale, solveRgbDrivesQ16(), step(), and xyzToOklabQ16().

Referenced by buildGamutMapRgbwQ16(), and fl::anonymous_namespace{pipeline.cpp.hpp}::buildWidePipelineQ16().

Here is the call graph for this function:

Here is the caller graph for this function: