pixel_stream.h

Go to the documentation of this file.

#pragma once
 
#include "fl/fs/fs.h"
#include "fl/stl/shared_ptr.h"         // For FASTLED_SHARED_PTR macros
#include "fl/stl/int.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/string.h"
#include "fl/video/pixel_sample.h"
namespace fl {
class filebuf;
using filebuf_ptr = fl::shared_ptr<filebuf>;
} // namespace fl
 
namespace fl {
namespace video {
 
FASTLED_SHARED_PTR(PixelStream);
 
// PixelStream reads frames from a filebuf to serve data to the video system.
// A single handle is used for both seekable files and non-seekable streams.
// Seekability is auto-detected via seek() at begin() time.
//
// FLED container support (issue #3072): on seekable handles, begin() peeks
// the first 12 bytes for the "FLED" magic. If present, the header is
// consumed, the embedded screenmap JSON is stashed, and frame reads start
// past the header. Legacy headerless `.rgb` files keep working unchanged.
// Spec: https://github.com/zackees/ledmapper/blob/main/docs/fled-format.md
class PixelStream {
  public:
    enum Type {
        kStreaming, // Non-seekable (e.g. memorybuf circular buffer)
        kFile,      // Seekable (e.g. posix_filebuf, SD card)
    };
 
    explicit PixelStream(int bytes_per_frame) FL_NO_EXCEPT;
 
    // Opens a handle. Streaming vs seekable is auto-detected:
    // seek(0, beg) succeeds → kFile, fails → kStreaming.
    bool begin(fl::filebuf_ptr h) FL_NO_EXCEPT;
 
    void close() FL_NO_EXCEPT;
    i32 bytesPerFrame() FL_NO_EXCEPT;
    bool readPixel(CRGB *dst) FL_NO_EXCEPT;
    bool readSample(PixelSample *out) FL_NO_EXCEPT;
    size_t readBytes(u8 *dst, size_t len) FL_NO_EXCEPT;
 
    bool readFrame(Frame *frame) FL_NO_EXCEPT;
    bool readFrameAt(fl::u32 frameNumber, Frame *frame) FL_NO_EXCEPT;
    bool hasFrame(fl::u32 frameNumber) FL_NO_EXCEPT;
    i32 framesRemaining() const FL_NO_EXCEPT; // -1 if this is a stream.
    i32 framesDisplayed() const FL_NO_EXCEPT;
    bool available() const FL_NO_EXCEPT;
    bool atEnd() const FL_NO_EXCEPT;
 
    i32 bytesRemaining() const FL_NO_EXCEPT;
    i32 bytesRemainingInFrame() const FL_NO_EXCEPT;
    bool rewind() FL_NO_EXCEPT; // Returns false for non-seekable streams.
    Type getType() const FL_NO_EXCEPT;
 
    // FLED v1 container accessors. True/non-empty only when begin() found
    // a valid FLED header on a seekable handle; otherwise empty / false.
    bool hasEmbeddedScreenMap() const FL_NO_EXCEPT;
    const fl::string &embeddedScreenMapJson() const FL_NO_EXCEPT;
    bool videoColor(fled::VideoColor *out) const FL_NO_EXCEPT;
    bool pixelStorage(fled::PixelStorage *out) const FL_NO_EXCEPT;
    // True only when the active source can be consumed by the legacy CRGB
    // playback path. Typed formats require a separate ingress consumer.
    bool isRgb8Playback() const FL_NO_EXCEPT;
    void setBestEffortFled(bool enabled) FL_NO_EXCEPT { mBestEffortFled = enabled; }
 
  private:
    fl::i32 mbytesPerFrame;
    const fl::i32 mBaseBytesPerFrame;
    fl::filebuf_ptr mHandle;
    Type mType;
 
    // Byte offset of the first frame in the file. 0 for legacy headerless
    // `.rgb` files; 12 + jsonLength for FLED-formatted files.
    fl::size_t mPayloadOffset = 0;
    fl::string mEmbeddedScreenMapJson;
    fl::u8 mFledPixelFormat = 0;
    fl::u8 mFledBytesPerLed = 0;
    bool mHasFledContainer = false;
    fled::VideoColor mVideoColor = {};
    bool mHasVideoColor = false;
    bool mBestEffortFled = false;
 
    // Non-seekable handles need a small magic probe. Raw stream bytes read
    // for that probe are replayed before the underlying handle is consumed.
    mutable fl::u8 mStreamingPrefix[4] = {};
    mutable fl::size_t mStreamingPrefixSize = 0;
    mutable fl::size_t mStreamingPrefixPos = 0;
    mutable bool mStreamingProbePending = false;
    mutable bool mStreamingRejected = false;
 
    bool probeStreamingMagic() const FL_NO_EXCEPT;
 
  public:
    virtual ~PixelStream() FL_NO_EXCEPT;
};
 
} // namespace video
using PixelStream = video::PixelStream;
using PixelStreamPtr = video::PixelStreamPtr;
} // namespace fl