brightness_within_budget()

static fl::u8 brightness_within_budget ( fl::u32 fixed_mW, fl::u32 controllable_mW, fl::u8 target_brightness, fl::u32 max_power_mW )

static

Definition at line 408 of file power_mgt.cpp.hpp.

                                                                        {
    const fl::u32 requested_mW =
        fixed_mW + scale_power_for_brightness(controllable_mW, target_brightness);
    if (requested_mW <= max_power_mW) {
        return target_brightness;
    }
    if (controllable_mW == 0 || max_power_mW <= fixed_mW) {
        // Nothing left to scale, or the baseline alone is already over the
        // budget. Either way no brightness meets it, and returning here is
        // also what keeps the subtraction below from underflowing and the
        // division from dividing by zero on an all-dark strip.
        return 0;
    }
    // The ratio is taken over the whole 0-255 scaled range, because
    // `controllable_mW` is the demand at *full* brightness. Scaling it by the
    // requested brightness first would answer "what fraction of the request
    // fits", which is smaller than "what brightness fits" by exactly that
    // fraction -- and the step-down below only ever decreases, so it cannot
    // recover it. The cap is where the request comes back in.
    //
    // The cap cannot actually fire from here: the caller only reaches this
    // branch when the request is already over budget, which is the same
    // inequality. It is kept because that argument runs through
    // `map_power_value`'s rounding, and a helper that clamps to its own
    // argument is cheaper than depending on that.
    const fl::u32 headroom_mW = max_power_mW - fixed_mW;
    const fl::u8 target_scaled = map_power_value(target_brightness);
    fl::u32 allowed_scaled = power_ratio_of_255(headroom_mW, controllable_mW);
    if (allowed_scaled > target_scaled) {
        allowed_scaled = target_scaled;
    }
    const fl::u32 recommended_scaled = static_cast<fl::u32>(allowed_scaled);
    fl::u8 recommended = unmap_power_value(static_cast<fl::u8>(recommended_scaled));
 
    // Then check the answer instead of trusting the division. Inverting the
    // ratio in scaled space is off by the rounding of whichever `scale32by8`
    // the platform compiled -- the FASTLED_SCALE8_FIXED form computes
    // `i * (s + 1) >> 8`, so the closed form lands about `controllable/256`
    // over the budget, which was 176 mW of a 5000 mW budget on the default
    // model. Demand is monotone in brightness, so stepping down until it fits
    // is exact whatever the rounding, and terminates: 0 always fits here,
    // because the branch above already returned for a budget under baseline.
    while (recommended > 0 &&
           fixed_mW + scale_power_for_brightness(controllable_mW, recommended) >
               max_power_mW) {
        --recommended;
    }
    return recommended;
}

References FL_NO_EXCEPT, map_power_value(), power_ratio_of_255(), scale_power_for_brightness(), and unmap_power_value().

Referenced by calculate_max_brightness_for_power_mW(), and calculate_max_brightness_for_power_mW().

Here is the call graph for this function:

Here is the caller graph for this function: