allocateTwoWhiteDrivesQ16()

bool fl::allocateTwoWhiteDrivesQ16	(	const TwoWhiteAllocationQ16 &	allocation,
		const i32(&)	xyz[3],
		i32(&)	drives[5] )

One pixel: XYZ in s16.16 to five drives – red, green, blue, white1, white2 – at whichever end of the feasible total the profile's policy names.

The method, and why it is not a search. Writing the total s = w1 + w2 and substituting w2 = s - w1 leaves the RGB drives as

(d0 - s * per_white2) - w1 * difference

which is the one-white shape with a shifted target. So at any fixed total the feasible w1 is again an interval, bounded by five lower and five upper bounds: three from the RGB drives, and two more because w1 and w2 = s - w1 are each a drive in their own right. Every one of those bounds is affine in s, so "some `w1` exists at this total" is exactly the conjunction of the pairwise inequalities lower_k(s) <= upper_j(s), each linear in s and each solvable for one s bound. Intersecting them gives the feasible totals in closed form – no bisection, no vertex enumeration, no per-pixel iteration (A3/B11).

That the interval has to be found rather than assumed is the whole point. Achievable totals form [s_lo, s_hi], which need not start at zero: a bright target is unreachable with the primaries alone, so a bisection seeded at zero has no feasible starting point and reports such targets unreachable. The first attempt at this made exactly that assumption (#4198).

At the chosen total the split is not free, which is measurement rather than assumption. The reference settles a free split by minimizing the sum of squares of the RGB drives, and an earlier revision did the same here; the feasible splits at the extreme total turn out to be a single point, so there was nothing for the rule to choose. Width measured 0.0 over 4000 random targets on the corpus's cool/warm device and 951 on a device built to make one drive's constraint parallel to w1 + w2 – the shape that could have produced an optimal edge. Two whites of the same colour are the exception, and there the reference's own tie-break is the end this takes.

False when no total keeps every drive in range, which means the target is outside the device hull – the gamut mapper's job, not this one's. drives is not written in that case.

Cost note, recorded rather than optimized away on a guess: up to 25 s16.16 divisions per pixel against the one-white path's six. Whether cross-multiplying the pairwise comparisons – which would leave one division and a great many i64 multiplies – wins on an 8-bit target is unmeasured, so the straightforward version is what ships.

Definition at line 394 of file white_allocation.cpp.hpp.

                                                              {
    i32 at_zero[3];
    solveRgbDrivesQ16(allocation.rgb_solve, xyz, at_zero);
    for (int i = 0; i < 3; ++i) {
        // A target this far out is not a rounding case, it is outside the
        // hull by a wide margin, and letting it through would be the only
        // way the bounds below could overflow.
        if (at_zero[i] > kTwoWhiteMaxColumn || at_zero[i] < -kTwoWhiteMaxColumn) {
            return false;
        }
    }
 
    // `w1 >= 0`, `w1 >= s - 1` (from `w2 <= 1`), `w1 <= 1`, `w1 <= s` (from
    // `w2 >= 0`). Every part of a bound is s16.16, the denominator included,
    // so a denominator of "one" is `kWhiteFullDrive` and not 1 -- writing a
    // raw 1 there scales those four bounds by 65536 and silently rejects
    // every target whose total runs past the primaries.
    SplitBound lowers[5];
    SplitBound uppers[5];
    int lower_count = 0;
    int upper_count = 0;
    lowers[lower_count++] = normalizedSplitBound(0, 0, kWhiteFullDrive);
    lowers[lower_count++] =
        normalizedSplitBound(-kWhiteFullDrive, kWhiteFullDrive, kWhiteFullDrive);
    uppers[upper_count++] = normalizedSplitBound(kWhiteFullDrive, 0, kWhiteFullDrive);
    uppers[upper_count++] = normalizedSplitBound(0, kWhiteFullDrive, kWhiteFullDrive);
 
    i64 low_total = 0;
    i64 high_total = 2 * static_cast<i64>(kWhiteFullDrive);
 
    for (int i = 0; i < 3; ++i) {
        // drive_i(w1, s) = (at_zero_i - s*per_white2_i) - w1*difference_i,
        // which must stay in [0, 1].
        const i32 slope = allocation.difference[i];
        if (slope == 0) {
            // The split cannot move this drive: the constraint is on the
            // total alone. `at_zero_i - s*per_white2_i` in [0, 1].
            const i32 per = allocation.per_white2[i];
            if (per == 0) {
                if (at_zero[i] < -kWhiteSlack ||
                    at_zero[i] > kWhiteFullDrive + kWhiteSlack) {
                    return false;
                }
                continue;
            }
            const i64 first = divideWhiteQ16(at_zero[i], per);
            const i64 second =
                divideWhiteQ16(at_zero[i] - kWhiteFullDrive - kTwoWhiteBoundSlack, per);
            const i64 upper = per > 0 ? first : second;
            const i64 lower = per > 0 ? second : first;
            if (upper < high_total) {
                high_total = upper;
            }
            if (lower > low_total) {
                low_total = lower;
            }
            continue;
        }
        // Dividing by a negative slope swaps which bound is which; that is
        // handled once, in normalizedSplitBound, by folding the sign.
        // The slack sits on the `drive <= 1` side and nowhere else, which
        // is the same asymmetry the one-white path argues for above. That
        // side can only *narrow* the white the policy may take, so tolerating
        // a drive 64 raw units past full -- exactly what the final range
        // check tolerates -- costs nothing. Putting slack on the `drive >= 0`
        // side would be different: the policy maximizes white, so it would
        // spend the slack on every pixel.
        //
        // Without it the exact hull corner is refused. Five emitters at full
        // drive solve, through a quantized matrix, to a target needing 57 raw
        // units more than a total of 2.0 can supply, so the feasible interval
        // comes out empty by less than a thousandth of a drive.
        const SplitBound at_full =
            normalizedSplitBound(at_zero[i] - kWhiteFullDrive - kTwoWhiteBoundSlack,
                                 -allocation.per_white2[i], slope);
        const SplitBound at_dark =
            normalizedSplitBound(at_zero[i], -allocation.per_white2[i], slope);
        if (!splitBoundInRange(at_full) || !splitBoundInRange(at_dark)) {
            return false;
        }
        if (slope > 0) {
            uppers[upper_count++] = at_dark;
            lowers[lower_count++] = at_full;
        } else {
            uppers[upper_count++] = at_full;
            lowers[lower_count++] = at_dark;
        }
    }
 
    // Some total admits a split exactly when every lower bound sits under
    // every upper bound there. Each pair is linear in the total, so this is
    // the closed form the header describes.
    for (int k = 0; k < lower_count; ++k) {
        for (int j = 0; j < upper_count; ++j) {
            if (!narrowTotalForPair(lowers[k], uppers[j], &low_total, &high_total)) {
                return false;
            }
        }
    }
    if (high_total < 0) {
        high_total = 0;
    }
    if (low_total > high_total) {
        return false;
    }
 
    const i64 total = allocation.policy == WhiteAllocationPolicy::RgbPreferred
                          ? low_total
                          : high_total;
 
    // At the chosen total the split is free, and the reference minimizes the
    // sum of squares of the RGB drives -- a quadratic in w1, so its minimum
    // is one division.
    i64 split_low = 0;
    i64 split_high = kWhiteFullDrive;
    for (int k = 0; k < lower_count; ++k) {
        const i64 value = splitBoundAt(lowers[k], total);
        if (value > split_low) {
            split_low = value;
        }
    }
    for (int j = 0; j < upper_count; ++j) {
        const i64 value = splitBoundAt(uppers[j], total);
        if (value < split_high) {
            split_high = value;
        }
    }
    if (split_low > split_high) {
        // Collapsed rather than empty. At either end of the total the split
        // bounds meet exactly, and they were derived through a quantized
        // matrix, so integer truncation can cross them by a few raw units --
        // measured at 21 on the RGB-preferred end of a target needing both
        // whites. Same answer as the one-white path gives its own boundary
        // case: take the point they collapse to and let the drive check
        // below decide whether the target is really reachable.
        if (split_low - split_high > kWhiteSlack) {
            return false;
        }
        const i64 middle = (split_low + split_high) / 2;
        split_low = middle;
        split_high = middle;
    }
 
    i64 at_total[3];
    for (int i = 0; i < 3; ++i) {
        at_total[i] = static_cast<i64>(at_zero[i]) -
                      ((static_cast<i64>(allocation.per_white2[i]) * total + 32768) >> 16);
    }
 
    // The low end, and there is nothing to choose. The reference settles the
    // split by minimizing the sum of squares of the RGB drives, and an
    // earlier revision here did the same -- it is a quadratic in the split,
    // so one division. Measurement removed it: at the *extreme* total the
    // feasible split is a single point, so there is no freedom for any rule
    // to exercise. Widest interval measured 0.0 over 4000 random targets on
    // the corpus's cool/warm device and 951 on a device built specifically
    // to make one drive's constraint parallel to `w1 + w2`, which is the
    // shape that could have produced an optimal edge.
    //
    // Where the split really is free -- two whites of the same colour, so
    // the difference column is zero and no RGB drive moves with the split --
    // the reference's own tie-break falls through to the lexicographically
    // smallest drives, which is this end. So the low end is not a
    // simplification away from the reference; it is what the reference does.
    //
    // See `ci/tests/test_color_rgbw_study.py`, which gates the whole
    // allocation against the reference and would fail if this stopped
    // holding.
    const i64 split = split_low;
 
    i32 rgb[3];
    for (int i = 0; i < 3; ++i) {
        const i64 drive =
            at_total[i] -
            ((static_cast<i64>(allocation.difference[i]) * split + 32768) >> 16);
        if (drive < -kWhiteSlack || drive > kWhiteFullDrive + kWhiteSlack) {
            return false;
        }
        rgb[i] = drive < 0 ? 0
                           : (drive > kWhiteFullDrive ? kWhiteFullDrive
                                                      : static_cast<i32>(drive));
    }
    const i64 second = total - split;
    if (second < -kWhiteSlack || second > kWhiteFullDrive + kWhiteSlack ||
        split < -kWhiteSlack || split > kWhiteFullDrive + kWhiteSlack) {
        return false;
    }
    drives[0] = rgb[0];
    drives[1] = rgb[1];
    drives[2] = rgb[2];
    drives[3] = split < 0 ? 0
                          : (split > kWhiteFullDrive ? kWhiteFullDrive
                                                     : static_cast<i32>(split));
    drives[4] = second < 0 ? 0
                           : (second > kWhiteFullDrive ? kWhiteFullDrive
                                                       : static_cast<i32>(second));
    return true;
}

References fl::TwoWhiteAllocationQ16::difference, FL_NO_EXCEPT, fl::TwoWhiteAllocationQ16::per_white2, fl::TwoWhiteAllocationQ16::policy, fl::TwoWhiteAllocationQ16::rgb_solve, RgbPreferred, solveRgbDrivesQ16(), and type_rank< T >::value.

Referenced by buildGamutMapRgbwwFromSolveQ16(), mapAndAllocateRgbwwQ16(), fl::anonymous_namespace{gamut_map.cpp.hpp}::RgbwwFeasible::operator()(), and processPixelWideLinearQ16().

Here is the call graph for this function:

Here is the caller graph for this function: