resolveVideoColor() [1/2]

ColorStatus fl::fled::resolveVideoColor	(	const fl::json &	envelope,
		fl::u8	pixelFormat,
		VideoColor *	out )

Definition at line 137 of file color.cpp.hpp.

                                                            {
    if (!out) return ColorStatus::NullOutput;
 
    const bool hasTuple = pixelFormatHasDefaultTuple(pixelFormat);
 
    // Locate video.color without requiring either level to exist.
    const fl::string kVideo("video");
    const fl::string kColor("color");
    bool present = false;
    fl::json colorNode;
    if (envelope.is_object() && envelope.contains(kVideo)) {
        const fl::json videoNode = envelope[kVideo];
        if (videoNode.is_object() && videoNode.contains(kColor)) {
            colorNode = videoNode[kColor];
            // An explicit JSON null means "not set" for most serializers.
            // Treat it as absent rather than rejecting the file - omitting
            // the key and nulling it should not have opposite outcomes.
            present = !colorNode.is_null();
        }
    }
 
    if (!present) {
        // Absent metadata: the format's default tuple is the historical
        // interpretation. Formats without one are simply unresolvable.
        VideoColor resolved;
        if (!defaultVideoColor(pixelFormat, &resolved)) {
            return ColorStatus::NoDefaultTuple;
        }
        *out = resolved;
        return ColorStatus::Ok;
    }
 
    if (!colorNode.is_object()) {
        return ColorStatus::NotAnObject;
    }
 
    const fl::string kPrimaries("primaries");
    const fl::string kTransfer("transfer");
    const fl::string kMatrix("matrix");
    const fl::string kRange("range");
 
    const bool hasP = colorNode.contains(kPrimaries);
    const bool hasT = colorNode.contains(kTransfer);
    const bool hasM = colorNode.contains(kMatrix);
    const bool hasR = colorNode.contains(kRange);
 
    // Key inheritance is scoped to formats that define a default tuple.
    // Everything else is all-or-nothing, so a future YCbCr format can never
    // silently inherit `matrix: rgb`.
    if (!hasTuple && !(hasP && hasT && hasM && hasR)) {
        return ColorStatus::IncompleteForFormat;
    }
 
    VideoColor resolved;
    if (!defaultVideoColor(pixelFormat, &resolved)) {
        // No tuple to seed from; every field is explicit here (checked above).
        resolved.primaries = ColorPrimaries::Bt709;
        resolved.transfer  = ColorTransfer::Srgb;
        resolved.matrix    = ColorMatrix::Rgb;
        resolved.range     = ColorRange::Full;
        for (fl::size i = 0; i < 8; ++i) resolved.customPrimaries[i] = 0.0f;
    }
    resolved.declared = true;
 
    // ---- primaries ----
    if (hasP) {
        const fl::json node = colorNode[kPrimaries];
        if (node.is_object()) {
            if (!readCustomPrimaries(node, resolved.customPrimaries)) {
                return ColorStatus::MalformedCustomPrimaries;
            }
            resolved.primaries = ColorPrimaries::Custom;
        } else if (node.is_string()) {
            auto s = node.as_string();
            if (!s) return ColorStatus::UnknownPrimaries;
            if (nameIs(*s, "bt709"))            resolved.primaries = ColorPrimaries::Bt709;
            else if (nameIs(*s, "display-p3"))  resolved.primaries = ColorPrimaries::DisplayP3;
            else if (nameIs(*s, "bt2020"))      resolved.primaries = ColorPrimaries::Bt2020;
            else return ColorStatus::UnknownPrimaries;
        } else {
            return ColorStatus::UnknownPrimaries;
        }
    }
 
    // ---- transfer ----
    if (hasT) {
        const fl::json node = colorNode[kTransfer];
        if (!node.is_string()) return ColorStatus::UnknownTransfer;
        auto s = node.as_string();
        if (!s) return ColorStatus::UnknownTransfer;
        switch (parseTransferName(*s)) {
        case TransferName::Srgb:   resolved.transfer = ColorTransfer::Srgb;   break;
        case TransferName::Bt709:  resolved.transfer = ColorTransfer::Bt709;  break;
        case TransferName::Linear: resolved.transfer = ColorTransfer::Linear; break;
        case TransferName::Pq:
        case TransferName::Hlg:
            // Reserved names: no v1 payload format can carry them.
            return ColorStatus::TransferConflictsWithFormat;
        case TransferName::Unrecognized:
            return ColorStatus::UnknownTransfer;
        }
    }
 
    // Transfer must agree with what the pixel format's bytes actually hold.
    if (isDisplayEncodedRgb(pixelFormat) &&
        resolved.transfer == ColorTransfer::Linear) {
        return ColorStatus::TransferConflictsWithFormat;
    }
    if (isLinearRgb(pixelFormat) && resolved.transfer != ColorTransfer::Linear) {
        return ColorStatus::TransferConflictsWithFormat;
    }
 
    // ---- matrix ----
    if (hasM) {
        const fl::json node = colorNode[kMatrix];
        if (!node.is_string()) return ColorStatus::UnknownMatrix;
        auto s = node.as_string();
        if (!s) return ColorStatus::UnknownMatrix;
        if (!nameIs(*s, "rgb")) {
            // "reserved" sends the author to the spec; "unrecognized" tells
            // them they typoed. Conflating the two wastes their time.
            return isReservedMatrixName(*s) ? ColorStatus::MatrixUnsupported
                                            : ColorStatus::UnknownMatrix;
        }
        resolved.matrix = ColorMatrix::Rgb;
    }
 
    // ---- range ----
    if (hasR) {
        const fl::json node = colorNode[kRange];
        if (!node.is_string()) return ColorStatus::UnknownRange;
        auto s = node.as_string();
        if (!s) return ColorStatus::UnknownRange;
        if (nameIs(*s, "full")) {
            resolved.range = ColorRange::Full;
        } else if (nameIs(*s, "limited")) {
            return ColorStatus::LimitedRangeUnsupported;
        } else {
            return ColorStatus::UnknownRange;
        }
    }
 
    *out = resolved;
    return ColorStatus::Ok;
}

References fl::json::as_string(), Bt2020, Bt709, fl::json::contains(), Custom, fl::fled::VideoColor::customPrimaries, fl::fled::VideoColor::declared, defaultVideoColor(), DisplayP3, fl::FL_NO_EXCEPT, Full, IncompleteForFormat, fl::json::is_null(), fl::json::is_object(), fl::json::is_string(), LimitedRangeUnsupported, Linear, MalformedCustomPrimaries, fl::fled::VideoColor::matrix, MatrixUnsupported, NoDefaultTuple, NotAnObject, NullOutput, Ok, pixelFormatHasDefaultTuple(), fl::fled::VideoColor::primaries, fl::fled::VideoColor::range, Rgb, Srgb, fl::fled::VideoColor::transfer, TransferConflictsWithFormat, UnknownMatrix, UnknownPrimaries, UnknownRange, and UnknownTransfer.

Referenced by fl::video::PixelStream::begin(), resolveVideoColor(), and fl::Fled::videoColor().

Here is the call graph for this function:

Here is the caller graph for this function: