video.h

Go to the documentation of this file.

#pragma once
 
#include "fl/stl/stdint.h"
 
#include "fl/stl/shared_ptr.h"         // For FASTLED_SHARED_PTR macros
#include "fl/stl/span.h"
#include "fl/stl/string.h"
#include "fl/stl/detail/memory_file_handle.h"
#include "fl/fx/fx1d.h"
#include "fl/video/pixel_sample.h"
#include "fl/stl/noexcept.h"
 
namespace fl {
 
struct SourceProfile;  // fl/gfx/color_profile.h
 
struct CRGB;
using CRGB = fl::CRGB;  // CRGB is now a typedef
 
// Forward declare classes
class filebuf;
using filebuf_ptr = fl::shared_ptr<filebuf>;
FASTLED_SHARED_PTR(Frame);
FASTLED_SHARED_PTR(VideoFxWrapper);
FASTLED_SHARED_PTR_NO_FWD(memorybuf);
 
namespace video {
class VideoImpl;
} // namespace video
using VideoImpl = video::VideoImpl;
using VideoImplPtr = fl::shared_ptr<VideoImpl>;
 
enum class FledPlaybackMode : fl::u8 {
    Strict,
    BestEffort,
};
 
// Video represents a video file that can be played back on a LED strip.
// The video file is expected to be a sequence of frames. Pass any filebuf
// to begin() — streaming vs seekable is auto-detected.
class Video : public Fx1d { // Fx1d because video can be irregular.
  public:
    static size_t DefaultFrameHistoryCount() {
#ifdef FL_IS_AVR
        return 1;
#else
        return 2; // Allow interpolation by default.
#endif
    }
    // frameHistoryCount is the number of frames to keep in the buffer after
    // draw. This allows for time based effects like syncing video speed to
    // audio triggers. If you are using a filehandle for you video then you can
    // just leave this as the default. For streaming byte streams you may want
    // to increase this number to allow momentary re-wind. If you'd like to use
    // a Video as a buffer for an fx effect then please see VideoFxWrapper.
    Video() FL_NO_EXCEPT;
    Video(size_t pixelsPerFrame, float fps = 30.0f,
          size_t frameHistoryCount =
              DefaultFrameHistoryCount()); // Please use FileSytem to construct
                                           // a Video.
    ~Video() FL_NO_EXCEPT;
    Video(const Video &) FL_NO_EXCEPT;
    Video &operator=(const Video &) FL_NO_EXCEPT;
 
    // Fx Api
    void draw(DrawContext context) override;
    string fxName() const override;
 
    // Api
    bool begin(fl::filebuf_ptr h);
    bool draw(fl::u32 now, fl::span<CRGB> leds);
    bool draw(fl::u32 now, Frame *frame);
    void end();
    bool finished();
    bool rewind();
    void setTimeScale(float timeScale);
    float timeScale() const;
    string error() const;
    // A caller-supplied error is persistent: it blocks admission until the
    // caller clears it. Admission errors recorded by begin() are not -- see
    // mAdmissionError.
    void setError(const string &error) FL_NO_EXCEPT {
        mError = error;
        mAdmissionError = false;
    }
    size_t pixelsPerFrame() const;
 
    // FLED v1 container (issue #3072): true / non-empty only when begin()
    // opened a FLED-formatted file (12-byte "FLED" magic header). Legacy
    // headerless `.rgb` files return false / empty string.
    // Spec: https://github.com/zackees/ledmapper/blob/main/docs/fled-format.md
    bool hasEmbeddedScreenMap() const FL_NO_EXCEPT;
    const fl::string &embeddedScreenMapJson() const FL_NO_EXCEPT;
    bool videoColor(fled::VideoColor *out) const FL_NO_EXCEPT;
    bool sourceProfile(SourceProfile *out) const FL_NO_EXCEPT;
    bool pixelStorage(fled::PixelStorage *out) const FL_NO_EXCEPT;
    bool readSample(video::PixelSample *out) FL_NO_EXCEPT;
    void setFledPlaybackMode(FledPlaybackMode mode) FL_NO_EXCEPT;
    void pause(fl::u32 now) override;
    void resume(fl::u32 now) override;
    void setFade(fl::u32 fadeInTime, fl::u32 fadeOutTime);
    i32 durationMicros() const; // -1 if this is a stream.
 
    // make compatible with if statements
    operator bool() const { return mImpl.get(); }
 
  private:
    // True when mError was recorded by a failed begin() rather than by
    // setError(). Such a failure describes one rejected source, not a dead
    // object, so the next begin() clears it and admits a new handle.
    void setAdmissionError(const string &error) FL_NO_EXCEPT {
        mError = error;
        mAdmissionError = true;
    }
 
    bool mFinished = false;
    bool mAdmissionError = false;
    VideoImplPtr mImpl;
    string mError;
    string mName;
};
 
// Wraps an Fx and stores a history of video frames. This allows
// interpolation between frames for FX for smoother effects.
// It also allows re-wind on fx that gnore time and always generate
// the next frame based on the previous frame and internal speed,
// for example NoisePalette.
class VideoFxWrapper : public Fx1d {
  public:
    VideoFxWrapper(FxPtr fx);
    ~VideoFxWrapper() FL_NO_EXCEPT override;
    void draw(DrawContext context) override;
    string fxName() const override;
    void setFade(fl::u32 fadeInTime, fl::u32 fadeOutTime);
 
  private:
    FxPtr mFx;
    VideoImplPtr mVideo;
    memorybufPtr mByteStream;
    float mFps = 30.0f;
};
 
} // namespace fl