buildStreamingPipelineQ16()

bool fl::buildStreamingPipelineQ16	(	const SourceProfile &	source,
		const colorimetric_response::EmitterProfile &	device,
		GamutPolicy	policy,
		StreamingPipelineQ16 *	out,
		const Chromaticity *	target_white = nullptr )

Bind a source declaration and a device profile into a pipeline.

False when either half is degenerate – collinear primaries, a white with no cone response, a device that cannot make a neutral. The individual stages decide that; this reports it.

The flux scalar starts at unity. setPipelineFluxQ16 is how brightness and the power limiter reach it, because they change between frames while everything else here does not. With target_white, D65 working XYZ is adapted to the selected physical neutral at bind time. A white outside the emitter gamut rejects the build; nullptr preserves the historical D65 output byte-for-byte.

Definition at line 140 of file pipeline.cpp.hpp.

                                                                              {
    if (out == nullptr) {
        return false;
    }
    out->gamut_policy = policy;
    if (!buildSourceMatrixQ16(source.primaries, &out->source)) {
        return false;
    }
 
    // Fold the source white's adaptation to D65 into the matrix above, so
    // the per-pixel path never pays for it. Skipped when the source already
    // renders to D65, where the transform is the identity and folding it
    // would only add a round trip's worth of quantization.
    //
    // Compared in s16.16 from the float's bits, so this check links no float
    // either (FastLED#4458). 1e-4 is 6.55 steps; 7 keeps the same window.
    const Chromaticity source_white = source.primaries.white;
    i32 white_x = 0;
    i32 white_y = 0;
    if (!q16FromFloatBits(source_white.x, &white_x) ||
        !q16FromFloatBits(source_white.y, &white_y)) {
        return false;
    }
    constexpr i32 kD65XQ16 = 20493;  // 0.3127
    constexpr i32 kD65YQ16 = 21561;  // 0.3290
    constexpr i32 kD65ToleranceQ16 = 7;  // ~1e-4
    const bool already_d65 = white_x > kD65XQ16 - kD65ToleranceQ16 &&
                             white_x < kD65XQ16 + kD65ToleranceQ16 &&
                             white_y > kD65YQ16 - kD65ToleranceQ16 &&
                             white_y < kD65YQ16 + kD65ToleranceQ16;
    if (!already_d65) {
        AdaptationMatrixQ16 adaptation;
        if (!buildBradfordMatrixQ16(source_white, kPipelineD65, &adaptation)) {
            return false;
        }
        foldAdaptationIntoSourceMatrix(adaptation, &out->source);
    }
 
    out->wide.reset();
    const bool is_rgb =
        device.topology == colorimetric_response::EmitterTopology::RGB;
    if (target_white == nullptr) {
        if (is_rgb) {
            if (!buildGamutMapQ16(device, &out->gamut)) return false;
        } else if (!buildWidePipelineQ16(device, nullptr, nullptr,
                                        &out->wide)) {
            return false;
        }
    } else {
        // The source and OKLab objective remain in D65 coordinates. Map the
        // physical gamut into that space by composing the inverse emitter
        // solve with Bradford D65 -> selected rendering white. The neutral
        // cap must be computed from the composed solve, not the raw profile.
        AdaptationMatrixQ16 to_target;
        if (!buildBradfordMatrixQ16(kPipelineD65, *target_white, &to_target))
            return false;
        EmitterSolveMatrixQ16 physical_solve;
        if (!buildRgbSolveMatrixQ16(device, &physical_solve)) return false;
        EmitterSolveMatrixQ16 effective_solve;
        for (int row = 0; row < 3; ++row) {
            for (int col = 0; col < 3; ++col) {
                i64 sum = 0;
                constexpr i64 kMax = 9223372036854775807LL;
                for (int k = 0; k < 3; ++k) {
                    // Each i32 product fits i64, but their sum need not.
                    const i64 term = static_cast<i64>(physical_solve.m[row][k]) *
                                     to_target.m[k][col];
                    if ((term > 0 && sum > kMax - term) ||
                        (term < 0 && sum < -kMax - term)) return false;
                    sum += term;
                }
                // Keep rounding/negation away from the i64 boundary too.
                if (sum > 2147483647LL * 65536 + 32768 ||
                    sum < -2147483648LL * 65536 - 32768) return false;
                const i64 value = sum >= 0 ? (sum + 32768) >> 16
                                           : -((-sum + 32768) >> 16);
                if (value < -2147483647LL - 1 || value > 2147483647LL)
                    return false;
                effective_solve.m[row][col] = static_cast<i32>(value);
            }
        }
        if (is_rgb) {
            if (!buildGamutMapFromSolveQ16(effective_solve, &out->gamut))
                return false;
        } else if (!buildWidePipelineQ16(device, target_white,
                                        &effective_solve, &out->wide)) {
            return false;
        }
    }
    out->response.reset();
    if (device.response_lut_size != 0) {
        const u16 size = device.response_lut_size;
        if (!validResponseLut(device.response_lut_r, size) ||
            !validResponseLut(device.response_lut_g, size) ||
            !validResponseLut(device.response_lut_b, size)) {
            return false;
        }
        shared_ptr<ResponseLutsQ16> response = make_shared<ResponseLutsQ16>();
        if (!response) return false;
        response->red.assign(device.response_lut_r, device.response_lut_r + size);
        response->green.assign(device.response_lut_g, device.response_lut_g + size);
        response->blue.assign(device.response_lut_b, device.response_lut_b + size);
        if (response->red.size() != size || response->green.size() != size ||
            response->blue.size() != size) return false;
        out->response = response;
    }
    out->transfer = source.transfer;
    out->flux = FluxScalar::unity();
    return true;
}

References buildBradfordMatrixQ16(), buildGamutMapFromSolveQ16(), buildGamutMapQ16(), buildRgbSolveMatrixQ16(), buildSourceMatrixQ16(), FL_NO_EXCEPT, foldAdaptationIntoSourceMatrix(), fl::AdaptationMatrixQ16::m, fl::EmitterSolveMatrixQ16::m, make_shared(), q16FromFloatBits(), fl::colorimetric_response::RGB, type_rank< T >::value, fl::FluxScalar::unity(), fl::Chromaticity::x, and fl::Chromaticity::y.

Referenced by buildPipelineForBinding().

Here is the call graph for this function:

Here is the caller graph for this function: