Cosmetic & needsUpdate()

wled00/FX.h

@@ -560,16 +560,16 @@ typedef struct Segment {
 
     // transition functions
     void     startTransition(uint16_t dur);     // transition has to start before actual segment values change
-    void     stopTransition(void);
+    void     stopTransition(void);              // ends transition mode by destroying transition structure
     void     handleTransition(void);
     #ifndef WLED_DISABLE_MODE_BLEND
     void     swapSegenv(tmpsegd_t &tmpSegD);    // copies segment data into specifed buffer, if buffer is not a transition buffer, segment data is overwritten from transition buffer
     void     restoreSegenv(tmpsegd_t &tmpSegD); // restores segment data from buffer, if buffer is not transition buffer, changed values are copied to transition buffer
     #endif
     uint16_t progress(void);                    // transition progression between 0-65535
-    uint8_t  currentBri(bool useCct = false);
+    uint8_t  currentBri(bool useCct = false);   // current segment brightness/CCT (blended while in transition)
-    uint8_t  currentMode(void);
+    uint8_t  currentMode(void);                 // currently active effect/mode (while in transition)
-    uint32_t currentColor(uint8_t slot);
+    uint32_t currentColor(uint8_t slot);        // currently active segment color (blended while in transition)
     CRGBPalette16 &loadPalette(CRGBPalette16 &tgt, uint8_t pal);
     CRGBPalette16 &currentPalette(CRGBPalette16 &tgt, uint8_t paletteID);
 
@@ -598,9 +598,9 @@ typedef struct Segment {
     uint32_t color_wheel(uint8_t pos);
 
     // 2D matrix
-    uint16_t virtualWidth(void)  const;
+    uint16_t virtualWidth(void)  const; // segment width in virtual pixels (accounts for groupping and spacing)
-    uint16_t virtualHeight(void) const;
+    uint16_t virtualHeight(void) const; // segment height in virtual pixels (accounts for groupping and spacing)
-    uint16_t nrOfVStrips(void) const;
+    uint16_t nrOfVStrips(void) const;   // returns number of virtual vertical strips in 2D matrix (used to expand 1D effects into 2D)
   #ifndef WLED_DISABLE_2D
     uint16_t XY(uint16_t x, uint16_t y); // support function to get relative index within segment
     void setPixelColorXY(int x, int y, uint32_t c); // set relative pixel within segment with color
@@ -747,23 +747,23 @@ class WS2812FX {  // 96 bytes
 
     void
 #ifdef WLED_DEBUG
-      printSize(),
+      printSize(),                                // prints memory usage for strip components
 #endif
-      finalizeInit(),
+      finalizeInit(),                             // initialises strip components
-      service(void),
+      service(void),                              // executes effect functions when due and calls strip.show()
-      setMode(uint8_t segid, uint8_t m),
+      setMode(uint8_t segid, uint8_t m),          // sets effect/mode for given segment (high level API)
-      setColor(uint8_t slot, uint32_t c),
+      setColor(uint8_t slot, uint32_t c),         // sets color (in slot) for given segment (high level API)
-      setCCT(uint16_t k),
+      setCCT(uint16_t k),                         // sets global CCT (either in relative 0-255 value or in K)
-      setBrightness(uint8_t b, bool direct = false),
+      setBrightness(uint8_t b, bool direct = false),    // sets strip brightness
-      setRange(uint16_t i, uint16_t i2, uint32_t col),
+      setRange(uint16_t i, uint16_t i2, uint32_t col),  // used for clock overlay
-      purgeSegments(void),
+      purgeSegments(void),                        // removes inactive segments from RAM (may incure penalty and memory fragmentation but reduces vector footprint)
       setSegment(uint8_t n, uint16_t start, uint16_t stop, uint8_t grouping = 1, uint8_t spacing = 0, uint16_t offset = UINT16_MAX, uint16_t startY=0, uint16_t stopY=1),
       setMainSegmentId(uint8_t n),
-      resetSegments(),
+      resetSegments(),                            // marks all segments for reset
-      makeAutoSegments(bool forceReset = false),
+      makeAutoSegments(bool forceReset = false),  // will create segments based on configured outputs
-      fixInvalidSegments(),
+      fixInvalidSegments(),                       // fixes incorrect segment configuration
-      setPixelColor(unsigned n, uint32_t c),
+      setPixelColor(unsigned n, uint32_t c),      // paints absolute strip pixel with index n and color c
-      show(void),
+      show(void),                                 // initiates LED output
       setTargetFps(uint8_t fps),
       addEffect(uint8_t id, mode_ptr mode_fn, const char *mode_name), // add effect to the list; defined in FX.cpp
       setupEffectData(void);                      // add default effects to the list; defined in FX.cpp
@@ -771,16 +771,15 @@ class WS2812FX {  // 96 bytes
     inline void restartRuntime()          { for (Segment &seg : _segments) seg.markForReset(); }
     inline void setTransitionMode(bool t) { for (Segment &seg : _segments) seg.startTransition(t ? _transitionDur : 0); }
     inline void setColor(uint8_t slot, uint8_t r, uint8_t g, uint8_t b, uint8_t w = 0)    { setColor(slot, RGBW32(r,g,b,w)); }
-    inline void fill(uint32_t c) { for (unsigned i = 0; i < getLengthTotal(); i++) setPixelColor(i, c); } // fill whole strip with color (inline)
-    // outsmart the compiler :) by correctly overloading
     inline void setPixelColor(unsigned n, uint8_t r, uint8_t g, uint8_t b, uint8_t w = 0) { setPixelColor(n, RGBW32(r,g,b,w)); }
     inline void setPixelColor(unsigned n, CRGB c)                                         { setPixelColor(n, c.red, c.green, c.blue); }
+    inline void fill(uint32_t c)          { for (unsigned i = 0; i < getLengthTotal(); i++) setPixelColor(i, c); } // fill whole strip with color (inline)
     inline void trigger(void)                                 { _triggered = true; }  // Forces the next frame to be computed on all active segments.
     inline void setShowCallback(show_callback cb)             { _callback = cb; }
-    inline void setTransition(uint16_t t) { _transitionDur = t; }
+    inline void setTransition(uint16_t t)                     { _transitionDur = t; } // sets transition time (in ms)
     inline void appendSegment(const Segment &seg = Segment()) { if (_segments.size() < getMaxSegments()) _segments.push_back(seg); }
-    inline void suspend(void) { _suspend = true; }
+    inline void suspend(void)                                 { _suspend = true; }    // will suspend (and canacel) strip.service() execution
-    inline void resume(void) { _suspend = false; }
+    inline void resume(void)                                  { _suspend = false; }   // will resume strip.service() execution
 
     bool
       paletteFade,
@@ -791,10 +790,11 @@ class WS2812FX {  // 96 bytes
       isUpdating(void),
       deserializeMap(uint8_t n=0);
 
-    inline bool isServicing(void) { return _isServicing; }
+    inline bool isServicing(void)          { return _isServicing; }           // returns true if strip.service() is executing
-    inline bool hasWhiteChannel(void) {return _hasWhiteChannel;}
+    inline bool hasWhiteChannel(void)      { return _hasWhiteChannel; }       // returns true if strip contains separate white chanel
-    inline bool isOffRefreshRequired(void) {return _isOffRefreshRequired;}
+    inline bool isOffRefreshRequired(void) { return _isOffRefreshRequired; }  // returns true if strip requires regular updates (i.e. TM1814 chipset)
-    inline bool isSuspended(void) { return _suspend; }
+    inline bool isSuspended(void)          { return _suspend; }               // returns true if strip.service() execution is suspended
+    inline bool needsUpdate(void)          { return _triggered; }             // returns true if strip received a trigger() request
 
     uint8_t
       paletteBlend,
@@ -805,32 +805,32 @@ class WS2812FX {  // 96 bytes
       getActiveSegsLightCapabilities(bool selectedOnly = false),
       setPixelSegment(uint8_t n);
 
-    inline uint8_t getBrightness(void) { return _brightness; }
+    inline uint8_t getBrightness(void)    { return _brightness; }       // returns current strip brightness
     inline uint8_t getMaxSegments(void)   { return MAX_NUM_SEGMENTS; }  // returns maximum number of supported segments (fixed value)
     inline uint8_t getSegmentsNum(void)   { return _segments.size(); }  // returns currently present segments
-    inline uint8_t getCurrSegmentId(void) { return _segment_index; }
+    inline uint8_t getCurrSegmentId(void) { return _segment_index; }    // returns current segment index (only valid while strip.isServicing())
-    inline uint8_t getMainSegmentId(void) { return _mainSegment; }
+    inline uint8_t getMainSegmentId(void) { return _mainSegment; }      // returns main segment index
     inline uint8_t getPaletteCount()      { return 13 + GRADIENT_PALETTE_COUNT; }  // will only return built-in palette count
-    inline uint8_t getTargetFps() { return _targetFps; }
+    inline uint8_t getTargetFps()         { return _targetFps; }        // returns rough FPS value for las 2s interval
-    inline uint8_t getModeCount() { return _modeCount; }
+    inline uint8_t getModeCount()         { return _modeCount; }        // returns number of registered modes/effects
 
     uint16_t
       getLengthPhysical(void),
       getLengthTotal(void), // will include virtual/nonexistent pixels in matrix
       getFps();
 
-    inline uint16_t getFrameTime(void) { return _frametime; }
+    inline uint16_t getFrameTime(void)    { return _frametime; }        // returns amount of time a frame should take (in ms)
-    inline uint16_t getMinShowDelay(void) { return MIN_SHOW_DELAY; }
+    inline uint16_t getMinShowDelay(void) { return MIN_SHOW_DELAY; }    // returns minimum amount of time strip.service() can be delayed (constant)
-    inline uint16_t getLength(void) { return _length; } // 2D matrix may have less pixels than W*H
+    inline uint16_t getLength(void)       { return _length; }           // returns actual amount of LEDs on a strip (2D matrix may have less LEDs than W*H)
-    inline uint16_t getTransition(void) { return _transitionDur; }
+    inline uint16_t getTransition(void)   { return _transitionDur; }    // returns currently set transition time (in ms)
 
     uint32_t
       now,
       timebase,
       getPixelColor(uint16_t);
 
-    inline uint32_t getLastShow(void) { return _lastShow; }
+    inline uint32_t getLastShow(void)   { return _lastShow; }           // returns millis() timestamp of last strip.show() call
-    inline uint32_t segColor(uint8_t i) { return _colors_t[i]; }
+    inline uint32_t segColor(uint8_t i) { return _colors_t[i]; }        // returns currently valid color (for slot i) AKA SEGCOLOR(); may be blended between two colors while in transition
 
     const char *
       getModeData(uint8_t id = 0) { return (id && id<_modeCount) ? _modeData[id] : PSTR("Solid"); }
@@ -839,9 +839,9 @@ class WS2812FX {  // 96 bytes
       getModeDataSrc(void) { return &(_modeData[0]); } // vectors use arrays for underlying data
 
     Segment&        getSegment(uint8_t id);
-    inline Segment& getFirstSelectedSeg(void) { return _segments[getFirstSelectedSegId()]; }
+    inline Segment& getFirstSelectedSeg(void) { return _segments[getFirstSelectedSegId()]; }  // returns reference to first segment that is "selected"
-    inline Segment& getMainSegment(void)      { return _segments[getMainSegmentId()]; }
+    inline Segment& getMainSegment(void)      { return _segments[getMainSegmentId()]; }       // returns reference to main segment
-    inline Segment* getSegments(void)         { return &(_segments[0]); }
+    inline Segment* getSegments(void)         { return &(_segments[0]); }                     // returns pointer to segment vector structure (warning: use carefully)
 
   // 2D support (panels)
     bool
@@ -877,7 +877,7 @@ class WS2812FX {  // 96 bytes
     std::vector<Panel> panel;
 #endif
 
-    void setUpMatrix();
+    void setUpMatrix();     // sets up automatic matrix ledmap from panel configuration
 
     // outsmart the compiler :) by correctly overloading
     inline void setPixelColorXY(int x, int y, uint32_t c)   { setPixelColor((unsigned)(y * Segment::maxWidth + x), c); }

wled00/FX_fcn.cpp

@@ -1143,7 +1143,7 @@ void WS2812FX::service() {
   _segment_index = 0;
   Segment::handleRandomPalette(); // move it into for loop when each segment has individual random palette
   for (segment &seg : _segments) {
-    if (_suspend) break; // immediately stop processing segments if suspend requested during service()
+    if (_suspend) return; // immediately stop processing segments if suspend requested during service()
 
     // process transition (mode changes in the middle of transition)
     seg.handleTransition();

wled00/wled.cpp

@@ -108,7 +108,7 @@ void WLED::loop()
     handlePresets();
     yield();
 
-    if (!offMode || strip.isOffRefreshRequired())
+    if (!offMode || strip.isOffRefreshRequired() || strip.needsUpdate())
       strip.service();
     #ifdef ESP8266
     else if (!noWifiSleep)

wled00/wled.h

@@ -8,7 +8,7 @@
  */
 
 // version code in format yymmddb (b = daily build)
-#define VERSION 2401010
+#define VERSION 2401040
 
 //uncomment this if you have a "my_config.h" file you'd like to use
 //#define WLED_USE_MY_CONFIG