pixel_stream.cpp.hpp

Go to the documentation of this file.

 
#include "fl/video/pixel_stream.h"
#include "fl/log/log.h"
#include "fl/stl/limits.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/json.h"
 
#define DBG FL_DBG
 
namespace fl {
namespace video {
 
// FLED v1 header layout (12 bytes). See
// https://github.com/zackees/ledmapper/blob/main/docs/fled-format.md
namespace {
constexpr fl::u8 kFledMagic[4] = {'F', 'L', 'E', 'D'};
constexpr fl::u8 kFledVersionV1 = 1;
constexpr fl::size_t kFledHeaderBytes = 12;
// Defensive cap on the embedded JSON to bound the worst-case heap
// allocation if a malformed file claims a giant json_length. Real
// screenmaps run ~500 B – ~50 KB; 1 MiB is well above that.
constexpr fl::size_t kFledMaxJsonBytes = 1u * 1024u * 1024u;
 
bool isFledMagicPrefix(const fl::u8* bytes, fl::size_t size) FL_NO_EXCEPT {
    for (fl::size_t i = 0; i < size; ++i) {
        if (bytes[i] != kFledMagic[i]) {
            return false;
        }
    }
    return true;
}
} // namespace
 
PixelStream::PixelStream(int bytes_per_frame) FL_NO_EXCEPT
    : mbytesPerFrame(bytes_per_frame), mBaseBytesPerFrame(bytes_per_frame),
      mType(kFile) {}
 
PixelStream::~PixelStream() FL_NO_EXCEPT { close(); }
 
bool PixelStream::begin(filebuf_ptr h) FL_NO_EXCEPT {
    close();
    if (!h || mBaseBytesPerFrame <= 0) {
        return false;
    }
    mHandle = h;
    mbytesPerFrame = mBaseBytesPerFrame;
    mPayloadOffset = 0;
    mEmbeddedScreenMapJson.clear();
    mFledPixelFormat = 0;
    mFledBytesPerLed = 0;
    mHasVideoColor = false;
    mHasFledContainer = false;
    mStreamingPrefixSize = 0;
    mStreamingPrefixPos = 0;
    mStreamingProbePending = false;
    mStreamingRejected = false;
    // Probe seekability: if seek-to-start succeeds, this is a seekable file.
    mType = mHandle->seek(0, seek_dir::beg) ? kFile : kStreaming;
    if (mType == kFile) {
        // A file without FLED magic remains a legacy headerless RGB stream.
        // Once magic is recognized, though, every invalidity is a container
        // error: falling back would render its header bytes as LEDs.
        if (mHandle->size() >= 4) {
            char hdr[kFledHeaderBytes];
            fl::size_t got = mHandle->read(hdr, kFledHeaderBytes);
            const bool hasFledMagic = got >= 4
                && static_cast<fl::u8>(hdr[0]) == kFledMagic[0]
                && static_cast<fl::u8>(hdr[1]) == kFledMagic[1]
                && static_cast<fl::u8>(hdr[2]) == kFledMagic[2]
                && static_cast<fl::u8>(hdr[3]) == kFledMagic[3];
            if (hasFledMagic) {
                const bool supportedFled = got == kFledHeaderBytes
                && static_cast<fl::u8>(hdr[4]) == kFledVersionV1
                && static_cast<fl::u8>(hdr[6]) == 0
                && static_cast<fl::u8>(hdr[7]) == 0
                && fled::bytesPerLed(static_cast<fl::u8>(hdr[5])) != 0;
                if (!supportedFled) {
                    close();
                    return false;
                }
                const fl::u8 pixelFormat = static_cast<fl::u8>(hdr[5]);
                const fl::u32 jsonLen =
                    static_cast<fl::u32>(static_cast<fl::u8>(hdr[8]))
                    | (static_cast<fl::u32>(static_cast<fl::u8>(hdr[9])) << 8)
                    | (static_cast<fl::u32>(static_cast<fl::u8>(hdr[10])) << 16)
                    | (static_cast<fl::u32>(static_cast<fl::u8>(hdr[11])) << 24);
                // Cap the JSON length against a defensive maximum BEFORE
                // doing any size arithmetic — guards against a malformed
                // file declaring a multi-gigabyte json_length that would
                // either overflow the offset calc or trigger a huge resize.
                const fl::size_t jsonLenSz = static_cast<fl::size_t>(jsonLen);
                const fl::size_t fileSize = mHandle->size();
                const bool jsonInRange = jsonLenSz <= kFledMaxJsonBytes
                    && jsonLenSz <= fileSize - kFledHeaderBytes;
                if (jsonInRange) {
                    mEmbeddedScreenMapJson.resize(static_cast<fl::size>(jsonLenSz));
                    fl::size_t jr = jsonLenSz > 0
                        ? mHandle->read(&mEmbeddedScreenMapJson[0], jsonLenSz)
                        : 0;
                    if (jr == jsonLenSz) {
                        mPayloadOffset = kFledHeaderBytes + jsonLenSz;
                        mFledPixelFormat = pixelFormat;
                        mFledBytesPerLed = fled::bytesPerLed(pixelFormat);
                        mHasFledContainer = true;
                        if (mbytesPerFrame % 3 != 0) {
                            close();
                            return false;
                        }
                        const fl::i32 ledCount = mbytesPerFrame / 3;
                        const fl::i32 bytesPerLed =
                            static_cast<fl::i32>(mFledBytesPerLed);
                        if (ledCount > (fl::numeric_limits<fl::i32>::max)() /
                                bytesPerLed) {
                            close();
                            return false;
                        }
                        mbytesPerFrame = ledCount * bytesPerLed;
                        if ((fileSize - mPayloadOffset) %
                            static_cast<fl::size_t>(mbytesPerFrame) != 0) {
                            close();
                            return false;
                        }
                        fl::json envelope;
                        if (!mEmbeddedScreenMapJson.empty()) {
                            envelope = fl::json::parse(mEmbeddedScreenMapJson);
                        }
                        const bool validEnvelope = mEmbeddedScreenMapJson.empty() ||
                            (envelope.has_value() && envelope.is_object());
                        if (!validEnvelope) {
                            close();
                            return false;
                        }
                        const bool colorOk =
                            fled::resolveVideoColor(envelope, mFledPixelFormat,
                                                    &mVideoColor) ==
                            fled::ColorStatus::Ok;
                        mHasVideoColor = colorOk;
                        if (!colorOk) {
                            fled::PixelStorage storage;
                            const bool advisoryRgb8 = pixelStorage(&storage) &&
                                storage.mFormat == fl::PixelFormat::Rgb8;
                            if (!mBestEffortFled || !advisoryRgb8) {
                                close();
                                return false;
                            }
                            FL_WARN("FLED video.color rejected; using explicit best-effort RGB8 playback");
                        }
                        // Stream is now positioned at the first frame byte.
                        return mHandle->available();
                    }
                    mEmbeddedScreenMapJson.clear();
                }
                // FLED magic was recognized, so malformed/truncated
                // containers must not become headerless raw RGB.
                close();
                return false;
            }
            // No magic: rewind so subsequent reads see raw RGB triplets.
            mHandle->seek(0, seek_dir::beg);
        }
        return mHandle->available();
    }
    // A partial FLED prefix stays buffered until enough bytes arrive to
    // classify it. A raw mismatch is replayed through readBytes().
    mStreamingProbePending = true;
    if (!probeStreamingMagic()) {
        close();
        return false;
    }
    return true;
}
 
void PixelStream::close() FL_NO_EXCEPT {
    mHandle.reset();
    mbytesPerFrame = mBaseBytesPerFrame;
    mPayloadOffset = 0;
    mEmbeddedScreenMapJson.clear();
    mFledPixelFormat = 0;
    mFledBytesPerLed = 0;
    mHasFledContainer = false;
    mHasVideoColor = false;
    mStreamingPrefixSize = 0;
    mStreamingPrefixPos = 0;
    mStreamingProbePending = false;
    mStreamingRejected = false;
}
 
bool PixelStream::probeStreamingMagic() const FL_NO_EXCEPT {
    if (!mStreamingProbePending) {
        return !mStreamingRejected;
    }
    while (mStreamingPrefixSize < 4 && mHandle && mHandle->available()) {
        const fl::size_t want = 4 - mStreamingPrefixSize;
        const fl::size_t got = mHandle->read(mStreamingPrefix + mStreamingPrefixSize,
                                             want);
        if (got == 0) {
            break;
        }
        mStreamingPrefixSize += got;
        if (!isFledMagicPrefix(mStreamingPrefix, mStreamingPrefixSize)) {
            mStreamingProbePending = false;
            return true;
        }
    }
    if (mStreamingPrefixSize == 4) {
        mStreamingProbePending = false;
        mStreamingRejected = true;
        return false;
    }
    return true;
}
 
i32 PixelStream::bytesPerFrame() FL_NO_EXCEPT { return mbytesPerFrame; }
 
bool PixelStream::readPixel(CRGB *dst) FL_NO_EXCEPT {
    if (!mHandle || !dst) {
        return false;
    }
    if (!isRgb8Playback()) {
        return false;
    }
    return readBytes(&dst->r, 3) == 3;
}
 
bool PixelStream::readSample(PixelSample *out) FL_NO_EXCEPT {
    if (!mHandle || !out) {
        return false;
    }
    fled::PixelStorage storage;
    fled::VideoColor color;
    if (!pixelStorage(&storage) || !videoColor(&color) ||
        storage.mFormat != fl::PixelFormat::Rgb16 ||
        storage.mComponentByteOrder != fled::ComponentByteOrder::LittleEndian) {
        return false;
    }
    fl::u8 bytes[6];
    if (readBytes(bytes, sizeof(bytes)) != sizeof(bytes)) {
        return false;
    }
    out->mStorage = storage;
    out->mColor = color;
    for (fl::u8 i = 0; i < 3; ++i) {
        const fl::size_t offset = static_cast<fl::size_t>(i) * 2;
        out->mComponents[i] = static_cast<fl::u16>(bytes[offset]) |
            (static_cast<fl::u16>(bytes[offset + 1]) << 8);
    }
    return true;
}
 
bool PixelStream::available() const FL_NO_EXCEPT {
    if (!mHandle) {
        return false;
    }
    if (mType == kStreaming) {
        if (!probeStreamingMagic() || mStreamingProbePending) {
            return false;
        }
        return mStreamingPrefixPos < mStreamingPrefixSize ||
               mHandle->available(mbytesPerFrame);
    }
    return mHandle->available();
}
 
bool PixelStream::atEnd() const FL_NO_EXCEPT {
    if (!mHandle) {
        return true;
    }
    if (mType == kStreaming) {
        return false;
    }
    return !mHandle->available();
}
 
bool PixelStream::readFrame(Frame *frame) FL_NO_EXCEPT {
    if (!mHandle || !frame) {
        return false;
    }
    if (mType == kFile && !framesRemaining()) {
        return false;
    }
    if (!isRgb8Playback()) {
        return false;
    }
    size_t n = 0;
    const fl::size_t pixels = static_cast<fl::size_t>(mbytesPerFrame) / 3;
    fl::span<CRGB> dst = frame->rgb();
    for (; n < pixels && n < dst.size() && readPixel(&dst[n]); ++n) {
    }
    if (mType == kFile) {
        DBG("pos: " << mHandle->pos());
    }
    return n * 3 == size_t(mbytesPerFrame);
}
 
bool PixelStream::hasFrame(fl::u32 frameNumber) FL_NO_EXCEPT {
    if (!mHandle) {
        return false;
    }
    if (mType == kStreaming) {
        // Streaming handle doesn't support seeking
        DBG("Not implemented and therefore always returns true");
        return true;
    }
    // Use size_t throughout so frameNumber * bytesPerFrame doesn't overflow
    // u32 for high-LED-count grids past ~1M frames.
    fl::size_t total_bytes = mHandle->size();
    fl::size_t frameBytes = static_cast<fl::size_t>(frameNumber)
        * static_cast<fl::size_t>(mbytesPerFrame);
    fl::size_t target = mPayloadOffset + frameBytes;
    return target < total_bytes;
}
 
bool PixelStream::readFrameAt(fl::u32 frameNumber, Frame *frame) FL_NO_EXCEPT {
    if (!mHandle || !frame || mType == kStreaming) {
        // Streaming handle doesn't support seeking
        FL_DBG("Streaming handle doesn't support seeking");
        return false;
    }
    if (!isRgb8Playback()) {
        return false;
    }
    fl::size_t frameBytes = static_cast<fl::size_t>(frameNumber)
        * static_cast<fl::size_t>(mbytesPerFrame);
    mHandle->seek(mPayloadOffset + frameBytes);
    if (mHandle->bytesLeft() == 0) {
        return false;
    }
    size_t read =
        mHandle->readRGB8(frame->rgb()) * 3;
 
    bool ok = int(read) == mbytesPerFrame;
    if (!ok) {
        DBG("readFrameAt failed - read: "
            << read << ", mbytesPerFrame: " << mbytesPerFrame << ", frame:"
            << frameNumber << ", left: " << mHandle->bytesLeft());
    }
    return ok;
}
 
i32 PixelStream::framesRemaining() const FL_NO_EXCEPT {
    if (mbytesPerFrame == 0)
        return 0;
    i32 bytes_left = bytesRemaining();
    if (bytes_left <= 0) {
        return 0;
    }
    return bytes_left / mbytesPerFrame;
}
 
i32 PixelStream::framesDisplayed() const FL_NO_EXCEPT {
    if (!mHandle) {
        return 0;
    }
    if (mType == kStreaming) {
        return -1;
    }
    if (mbytesPerFrame == 0) {
        return 0;
    }
    fl::size_t pos = mHandle->pos();
    if (pos < mPayloadOffset) return 0;
    return static_cast<i32>((pos - mPayloadOffset) / mbytesPerFrame);
}
 
i32 PixelStream::bytesRemaining() const FL_NO_EXCEPT {
    if (!mHandle) {
        return 0;
    }
    if (mType == kStreaming) {
        // Use (max)() to prevent macro expansion by Arduino.h's max macro
        return (fl::numeric_limits<i32>::max)();
    }
    return mHandle->bytesLeft();
}
 
i32 PixelStream::bytesRemainingInFrame() const FL_NO_EXCEPT {
    if (mbytesPerFrame == 0) {
        return 0;
    }
    return bytesRemaining() % mbytesPerFrame;
}
 
bool PixelStream::rewind() FL_NO_EXCEPT {
    if (!mHandle || mType == kStreaming) {
        return false;
    }
    // Rewind to the start of the payload, not the start of the file —
    // skips the FLED header on container-formatted streams.
    mHandle->seek(mPayloadOffset);
    return true;
}
 
PixelStream::Type PixelStream::getType() const FL_NO_EXCEPT {
    return mType;
}
 
bool PixelStream::hasEmbeddedScreenMap() const FL_NO_EXCEPT {
    return !mEmbeddedScreenMapJson.empty();
}
 
const fl::string &PixelStream::embeddedScreenMapJson() const FL_NO_EXCEPT {
    return mEmbeddedScreenMapJson;
}
 
bool PixelStream::videoColor(fled::VideoColor *out) const FL_NO_EXCEPT {
    if (!out || !mHasFledContainer || !mHasVideoColor) {
        return false;
    }
    *out = mVideoColor;
    return true;
}
 
bool PixelStream::pixelStorage(fled::PixelStorage *out) const FL_NO_EXCEPT {
    return mHasFledContainer && out && fled::toPixelStorage(
        static_cast<fled::PixelFormat>(mFledPixelFormat), out);
}
 
bool PixelStream::isRgb8Playback() const FL_NO_EXCEPT {
    return !mHasFledContainer ||
        mFledPixelFormat == static_cast<fl::u8>(fled::PixelFormat::Rgb8);
}
 
size_t PixelStream::readBytes(u8 *dst, size_t len) FL_NO_EXCEPT {
    if (!mHandle || !dst) {
        return 0;
    }
    if (mType == kStreaming &&
        (!probeStreamingMagic() || mStreamingProbePending)) {
        return 0;
    }
    size_t bytesRead = 0;
    while (bytesRead < len && mStreamingPrefixPos < mStreamingPrefixSize) {
        dst[bytesRead++] = mStreamingPrefix[mStreamingPrefixPos++];
    }
    if (mType == kStreaming) {
        while (bytesRead < len && mHandle->available(len - bytesRead)) {
            if (mHandle->read(dst + bytesRead, 1)) {
                bytesRead++;
            } else {
                break;
            }
        }
    } else {
        while (bytesRead < len && mHandle->available()) {
            if (mHandle->read(dst + bytesRead, 1)) {
                bytesRead++;
            } else {
                break;
            }
        }
    }
    return bytesRead;
}
 
} // namespace video
} // namespace fl