Scanner (Seg Line) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info) (Trails look much better IRL)

This effect creates a customizable set of "scanner" waves. Think like the classic Cylon visor eye. You have a lot of control over what the scanner waves look like, how they bounce, if/when the change colors, etc. It is a cross between the Particles and Larson Scanner effects, being more focused than the former, but more general than the latter.

The effect is adapted to work on segment lines for 2D use. The scanner wave colors will be copied along segment lines.

Supports color modes for both the main and background colors.

Note that the effect requires an array of CRGB colors and a particle set of length numWaves. These are allocated dynamically, so, to avoid memory fragmentation, when you create the effect, you should set numWaves to the maximum value you expect to use. See Memory Management for more details.

The effect is designed to build a set of scanner waves (particles) for you. This allows you to create classic scanner types, like the Cylon and Kitt scanners, but also gives you access to more complex, custom, scanning patterns. The effect creates a set of evenly spaced waves, all with the same trail, speed, size, etc settings. The effect is unique in that it can cycle through wave colors automatically. Note that the waves use a pattern/palette combo for colors like in other effects.

• trailType -- The trail type of the waves (see Trail Types below).

• trailSize -- The length of the trails. Using 0 will turn off the trails for the waves, (must turn them back on manually by setting the trailType for the effect).

• size -- The size of the main body of the waves (not the trails) (min value 1).

• bounce -- If true, the waves will reverse, "bounce back", at the end of the segment set. If false the waves will wrap back to the start at each segment set end.

There are various options for the wave trails, set by the trailType setting. You can also opt to have the trails chosen at random from a customizable group.

• 0 -- no trails.
• 1 -- One trail facing away from the direction of motion (like a comet).
• 2 -- two trails, coming from both sides of the wave.
• 3 -- One trail facing towards the direction of motion.
• 4 -- Infinite trails that persist after the wave, and are not faded.

For example, with a trail length of 4, and a body size of 1, the modes will produce: (The trail head is *, - are the trail, wave is moving to the right ->)

• 0: *
• 1: ----*
• 2: ----*----
• 3: *----
• 4: *****

• Wave colors are tied to the effect palette and pattern (you can set the palette as the pattern).

• Waves will either alternate colors every time they bounce/wrap, every other time they bounce, or never. (see Color Change Settings below).

• Colors can be set to be chosen at random (see randModes below).

• When/if waves cross, you can opt to have them blended together, or just overwrite each other. Controlled with the blend setting. Blending is not recommended for colored backgrounds. See "blending" entry in Particles for more.

• By default, the trails dim quickly in a non-linear fashion. This makes the particle "heads" brighter and standout more, which, in my opinion, looks better then just using a linear fade. You can control the linearity of the trail fades using the dimPow setting. A default of 80 is used in this effect. You can read the dimPow notes in Particle Utils) for more.

Waves will either alternate colors every time they bounce/wrap, every other time they bounce, or never. This is controlled by the bounceChange setting:

• bounceChange:

  • If bounce is true and bounceChange is:
    • True, the waves will change colors every time they bounce.
    • False then they will change every other time.
  • If bounce is false:
    • The waves will change colors every time they wrap to 0.

• To lock the waves colors so that they never change, use randMode 3.

Sets how wave colors will be chosen when they change.

• 0 -- Colors will be chosen in order from the pattern (not random).
• 1 -- Colors will be chosen randomly from the pattern.
• 2 -- Colors will be chosen at random from the pattern, but the same color won't be repeated in a row.
• 3 -- New colors will not be chosen, the wave colors will be locked to whatever they currently are.

For a wave to bounce, it must reverse its direction once it hits either end of the segment set. However, how/when it bounces is a matter of opinion.

I have opted for the following:

• The wave only bounces when its main body (not trail) reaches an end point.

• Both the front and rear trails wrap back on themselves as the wave bounces. Ie the head of the trail moves back down the strip, opposite the direction of the wave.

• The rear trail is always drawn last. In practice this means that particles with two trails mimic the classic "Cylon" scanner look, where the front of the trail disappears off the strip (it is actually wrapping back, but is over written by the rear trail, which is drawn after). While for particles with only a rear trail, it naturally fades as like it would for a physical streamer/flame/etc.

• For particles with only a front trail the trail also wraps back, but under the wave. This does look a little weird, but there's not a good real world approximation to this kind of wave, so w/e.

• For particles where the body size is larger than one, when a bounce happens, the entire body reverses direction at once. This is not visually noticeable, and makes coding easier. However, it does mean there's no "center" of a wave.

ScannerSL scanner(mainSegments, CRGB::Red, 0, 2, 1, 5, 1, true, true, true, true, true, 80);
/*  Will do a classic "Kitt" scanner, with 2 red particles moving back and forth, meeting in the middle of the segment set
    The background is blank.
    The scan particles will have 1 trail of length 5, a body size of 1.
    The particles will start with alternating directions, one particle will start at each end of the segment set
    they will bounce at each segment set end, and blend together when they meet
    The particles move at 80ms */

ScannerSL scanner(mainSegments, cybPnkPal_PS, 0, 3, 2, 4, 2, true, false, false, false, true, false, 80);
/*  Will automatically create a set of 3 scanner particles
    The particles will be spaced evenly on the segment set (makeEndWave is false)
    The particles will take their colors from the cybPnkPal_PS palette, with a blank background.
    Each particle will have 2 trails of length 4, with a body size of 2
    The particles will start in the forward direction (not set to alternate)
    The particles will not bounce at each end of the segment set, and will wrap instead
    (bounceChange is true, but doesn't matter for wrapping particles)
    Blending is turned off
    The particles move at 80ms */

/*  (note that there is an additional constructor that uses a pattern. This is 
    the same as the above constructor, but a patternPS is included before the palette) */

//Constructor using a single color
ScannerSL(SegmentSetPS &SegSet, CRGB Color, CRGB BGColor, uint16_t numWaves, uint8_t TrailType, uint16_t TrailSize,
          uint16_t Size, bool direction, bool alternate, bool makeEndWave, bool Bounce, bool Blend, uint16_t Rate);

//Constructor for using a pattern with a custom set of repeating waves
ScannerSL(SegmentSetPS &SegSet, patternPS &Pattern, palettePS &Palette, CRGB BGColor, uint16_t numWaves, 
          uint8_t TrailType, uint16_t TrailSize, uint16_t Size, bool direction, bool alternate, bool makeEndWave, 
          bool Bounce, bool BounceChange, bool Blend, uint16_t Rate);

//Constructor for using the palette as the pattern with a custom set of repeating waves
ScannerSL(SegmentSetPS &SegSet, palettePS &Palette, CRGB BGColor, uint16_t numWaves, uint8_t TrailType, uint16_t TrailSize, 
          uint16_t Size, bool direction, bool alternate, bool makeEndWave, bool Bounce, bool BounceChange, 
          bool Blend, uint16_t Rate);

• SegmentSetPS* segSet -- The Segment Set the effect will draw on. See common vars segSet entry for more details.

• palettePS* palette (optional, see constructors) -- The set of colors the effect will use. See palettes. It is a pointer. See common vars palette entry for more details.

• patternPS* pattern (optional, see constructors) -- The color pattern the effect will use. See patterns. It is a pointer. See common vars pattern entry for more details.

• CRGB color (optional, see constructors) -- A single color for the effect. The color will be placed into the effect's local palette, paletteTemp for use. A pattern for the single color will also be created and stored in the effect's local patternTemp variable.

• CRGB* bgColor -- The color used for background pixels. Is a pointer, allowing you to bind it to an external color. By default it's bound the effect's local, bgColorOrig color. See common vars bgColor entry for more details.

• uint16_t numWaves -- How many scan waves will be created. The waves will be evenly spaced across the segment set. You can re-configure the waves later using makeWaveSet().

• uint8_t trailType -- The trail type of the waves. (See Inputs Guide above).

• uint8_t trailSize -- The length of the wave trails. Using 0 will turn off the trails for the waves. (must turn them back on manually by setting the trailType for effect).

• uint16_t size -- The size of the main body of the waves (not the trails) (min value 1).

• bool direction -- The starting direction for the waves (true = forward). The first wave will always use this direction.

• bool alternate -- If true, the the wave starting directions will alternate with each wave ie, if direction is true, then the first wave will go forward, the next in reverse, etc.

• bool makeEndWave -- (See makeWaveSet() function entry below).

• bool bounce -- Sets if the waves reverse ("bounce") at each end of the segment set, if not then they wrap to the start/end.

• bool bounceChange (set false for the single color constructor) -- Sets when the wave colors change. (See Inputs Guide above).

• bool blend -- blend -- If true, then waves' colors will be blended together when they pass each other. (See Wave Colors in Inputs Guide above).

• uint16_t* rate -- Update rate (ms). Is a pointer, allowing you to bind it to an external variable. By default it's bound the effect's local variable, rateOrig. See common vars rate entry for more.

• uint8_t colorMode (default 0) -- The colorMode use for the effect, also see common vars colorMode entry for more details.

• uint8_t bgColorMode (default 0) -- The colorMode used for the background pixels, also see common vars colorMode entry for more details.

• bool fillBg (default false) -- If true, then all pixels will be re-colored with each update(), rather than just drawing those that have changed. See common vars fillBg entry for more details.

• int8_t dimPow (default 80, min -127, max 127) -- Adjusts the rate of dimming for the trails (see Wave Colors in Intro).

• particleSetPS particleSet -- The particle set used for the wave particles (you can use it to directly set the position of the waves).

• bool showNow (default true) -- Controls if the effect "draws" during each update cycle by calling FastLED.show(). Common to all effects. See common vars showNow entry for more details.

• void setPaletteAsPattern();

  Sets the effect pattern to match the current effect palette. See Common Functions for more.

• void reset();

  Resets all the waves to their start locations and sets their starting colors. Also fills the background to remove any old waves.

• void makeWaveSet( uint16_t numWaves, bool direction, bool alternate, bool makeEndWave );

  This function both creates and positions a set of waves evenly across the segment set. It is automatically called as part of the constructors, so you only need to call it manually if you want to make/adjust a new wave set. Note that makeWaveSet() only sets where the waves start and their directions. Does not clear any left-over wave bits from the segment set!

  • numWaves -- How many scan waves will be created.

  • direction -- The starting direction for the waves (true = forward). The first wave will always use this direction.

  • alternate -- If true, the the wave starting directions will alternate with each wave ie, if direction is true, then the first wave will go forward, the next in reverse, etc

  • makeEndWave -- Sets how the waves are spaced. It is important for setting the starting positions of your waves so that they remain evenly spaced when moving, depending on if they wrap or bounce at each segment end.

    • If you have a single wave, makeEndWave has no effect; the wave always starts at 0.

    • For multiple waves, if makeEndWave is true, the waves will be spaced such that one wave starts at the end of the segment set. (Note that if makeEndWave is true, you should also set alternate true, otherwise the end/start waves will overlap)

    • If makeEndWave is false, then the waves will be spaced evenly across the segment set, starting from 0.

    • For example, lets say we have 9 LEDs, and want three waves with size 1, no trails:

      start -- -- -- -- -- -- -- -- -- (each -- is an LED).

      If we set makeEndWave true, then the initial setup will look like:

      start ** -- -- -- ** -- -- -- ** (each ** is an wave).

      Each wave is evenly spaced, but making sure that one wave starts at the end (doing numLines / (numWaves - 1) for spacing).

      If makeEndWave is false, then the initial setup will look like:

      start ** -- -- ** -- -- ** -- -- (each ** is an wave).

      Evenly spaced (doing numLines / numWaves for spacing).

• void update();

  Updates the effect.

• uint16_t numWaves -- The number of wave particles. Set using makeWaveSet().