Rain (Seg Line) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Looks Like this Sample, But Drawn Along Segment Lines

An effect for producing a random set of falling particles, like rain, or the classic "Matrix" code animation. Drops spawn at the start (or end) of each segment line in the segment set and "fall down" to the end of each line. The falling direction is configurable. This effect uses particles as the rain drops. See Particles, and Particle Utils page for the full details on particles.

For a similar effect see Rain (Seg), which moves drops along segments rather than segment lines (making it "orthogonal" to this effect).

There are numerous options for customizing the rain drops, such as trail type, speed, size, etc. You can also configure each drop's properties to be chosen at random from set ranges. There are also more general settings for how often drops spawn, how the background is drawn, and if the drops should blend together if they pass over each other. The drop colors can either be a static color or picked randomly from a palette.

Supports color modes for both the main and background colors.

You can change the drop variables (speed, size, the ranges) on the fly. As drops spawn they will use the new values.

Note that the effect requires an array of particles and a booleans of size maxNumDrops * numLines. These are allocated dynamically, so, to avoid memory fragmentation, when you create the effect, you should set maxNumDrops to the maximum value you expect to use. See Memory Management for more details.

Most of the effect inputs are focused on customizing the rain particles. The rain drops are spawned and then de-spawned as they move on/off the segments, so you don't have a fixed set of particles to work with. Instead, when a particle spawns, it becomes "active", and its settings are randomized based on the effect's particle settings. These settings correspond to the particle struct settings. For example, the effect's trailSize setting corresponds to the particle's trailSize, so when a particle spawns, its trailSize is set to the effect's trailSize. I won't go over these base settings in detail, but I will discuss the randomization options below.

There are various options for the rain drop's 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 particle.
• 3 -- One trail facing towards the direction of motion.
• 4 -- Infinite trails that persist after the particle, 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, particle is moving to the right ->)

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

By default, the trails dim quickly in a non-linear fashion. This makes the drop "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.

You can have the rain drops chose a random trail type from a customizable selection. To access this feature set trailType to 6 (or use one of the trail customization constructors). There is a flag for each type of trail. Each drop's trail will be picked randomly from the flags set true. If no flags are set, drops will spawn with no trails.

Trail Flags:

• noTrails -- Allows drops with no trails.
• oneTrail -- Allows drops with one trailing trail.
• twoTrail -- Allows drops with two trails.
• revTrail -- Allows drops with one reversed trails.
• infTrail -- Allows drops with infinite trails.

For example, if noTrails, twoTrail, infTrail are true then drops can spawn with no trails, two trails or infinite trails.

When a rain drop particle is spawned, it's speed, size, and trail size are set to the effect settings, speed, size, and trailSize. You can opt to randomize these values for each rain drop by setting the following ranges:

• speedRange -- The amount the speed may vary up from the base speed ( ie speed + random(speedRange) ) (ms).

• trailRange -- The amount the trailSize can vary from the base size ( ie trailSize + random(trailRange) ).

• sizeRange -- The amount the size can vary from the base size ( ie size + random(sizeRange) ).

Due to the way the effect is programmed, particles at the end in the particle set will run "in front" of those earlier in the set. This means that when two particles pass each other, the later one will be drawn over the earlier one.

You can adjust this behavior by turning on blend, which will add particle colors together as they pass by each other. However this does have a few draw backs:

1. Due to the way particle trails are drawn, this forces the background to be re-drawn each update cycle, which may have a performance impact depending on your strip length, update rate, etc.

2. For colored backgrounds, the particles colors are added to the background colors. This will in most cases significantly change the particle colors. For example, blue particles running on a red background will appear purple (blue + red = purple). While this can be used to create some nice effects, (like ocean-ish of lava-ish looking things), overall I do not recommend using blend for colored backgrounds.

As the rain drops move, they naturally fill in the background behind them. This allows you to create a neat start to the effect by letting the first rain drops replace whatever was previously on the segment set over time as the spawn in and move. You can also opt to pre-fill the background instead. the bgPrefill setting controls this behavior (true will pre-fill the background). The effect also features the more standard fillBg, which fills the background every cycle. Finally, note that backgrounds are not drawn by drops with infinite trails (trail mode 4), and that turning on fillBg will break their trails.

A drop will spawn if random(spawnBasis) <= spawnChance. spawnBasis is default to 1000, so you can go down to sub 1% percentages. Note that the effect tries to spawn any inactive drops with each update(), although only one drop can spawn at a time. This means that how densely your drops spawn depends a lot on the effect update rate and how many drops you can have max. Even with quite low percentages, at the default update rate (see below), drops will probably spawn quite close together.

Note that unlike other effects, the update rate is pre-set for you at 5ms, which helps catch each of the rain drop's updates on time (hopefully!). You see, each rain drop has its own speed (update rate), but we still want be able to update the effect with a single update() call. I could have ignored the "rate" setting, and just updated all the rain drops whenever you call update(). However, the drops are re-drawn every update(), even if they haven't moved, so this becomes problematic, especially when working with multiple effects or segment sets, where you want more control over when you update. Instead I opted to treat the effect as normal, and keep the overall update rate, but default it to a very fast 5ms. Usually I set my speeds to multiples of 10, so hopefully this default will catch most particles on time. You are free to change the update rate as needed by setting rateOrig.

/*  A "quick" constructor without options for size, trail, or speed ranges and only one trail type supported.
    All ranges are default to 0.
    There is a similar constructor for using a single color, just replace the palette with a color. */

//rainSL.bgColorMode = 6; //=> optional for next effect, will cycle the background through the rainbow, place in Arduino setup()
RainSeg rainSL(mainSegments, cybPnkPal_PS, 0, true, 10, 4, 1, 1, 5, 80, true);
/*  Will spawn drops on the mainSegments set, picking colors from the cybPnkPal_PS palette
    The background is blank, and it will be pre-filled before the drops spawn
    The drops have a spawn chance of 10/1000 (1% chance of spawning each update cycle)
    There is a maximum of 4 drops running concurrently on each segment
    The drops are size 1 and have a single trail trail of length 5 (trail mode 1)
    The drops move with a base speed of 80ms
    Drops will spawn at the first segment and move towards the last
    
/*  A more extensive constructor will all the options for drops
    Also comes as a palette variant; replace the color with a palette in the constructor */

RainSeg rainSeg(mainSegments, CRGB::Green, CRGB::Red, false, 10, 4, 1, 3, 2, 4, true, true, false, false, false, 60, 40);
/*  Will spawn green drops on the mainSegments set
    The background is red, and it will not be pre-filled before the drops spawn
    The drops have a spawn chance of 10/1000 (1% chance of spawning each update cycle)
    There is a maximum of 4 drops running concurrently on each segment
    The drops have a minimum size of 1, with a range of 3 (max size 4)
    The drops have minimum trail size (if they have them) of 2 with a range of 4 (max size 6)
    Drops can spawn with no trails or a single trial,
    but will not spawn with double, reversed, or infinite trails
    Drops will have a base speed of 60ms and a speed range of 40ms (for a min speed of 100ms)
    Drops will spawn at the last segment and move towards the first */

//Constructor for palette colors, no range options
RainSL(SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, bool BgPrefill, uint16_t SpawnChance, 
       uint8_t MaxNumDrops, uint16_t Size, uint8_t TrailMode, uint8_t TrailSize, 
       uint16_t Speed, bool Direct);

//Constructor for palette colors with range and trail options
RainSL(SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, bool BgPrefill, uint16_t SpawnChance,
       uint8_t MaxNumDrops, uint16_t Size, uint16_t SizeRange, uint8_t TrailSize, uint8_t TrailRange, 
       bool NoTrails, bool OneTrail, bool TwoTrail, bool RevTrail, bool InfTrail, 
       uint16_t Speed, uint16_t SpeedRange, bool Direct);

//Constructor for single color, no range options
RainSL(SegmentSetPS &SegSet, CRGB Color, CRGB BgColor, bool BgPrefill, uint16_t SpawnChance, 
       uint8_t MaxNumDrops, uint16_t Size, uint8_t TrailType, uint8_t TrailSize, 
       uint16_t Speed, bool Direct);

//Constructor for single colors with range and trail options
RainSL(SegmentSetPS &SegSet, CRGB Color, CRGB BgColor, bool BgPrefill, uint16_t SpawnChance, 
       uint8_t MaxNumDrops, uint16_t Size, uint16_t SizeRange, uint8_t TrailSize, uint8_t TrailRange, 
       bool NoTrails, bool OneTrail, bool TwoTrail, bool RevTrail, bool InfTrail, 
       uint16_t Speed, uint16_t SpeedRange, bool Direct);

• 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.

• 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.

• 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.

• bool bgPrefill -- If true, then the background will be filled when the effect first runs. Otherwise the drops will fill it in as they move along (see Background Pre-filling in Inputs Guide).

• uint8_t spawnChance -- The chance a drop will spawn (if able) each cycle out of 100, higher val => more likely to spawn.

• uint8_t maxNumDrops -- The maximum number of rain drop particles that can be active on a segment (not the whole segment Set!) at one time. Can be changed later using setupDrops().

• uint16_t size -- The minimum size of the body of the drops (doesn't include trails) (min value 1).

• uint16_t sizeRange (optional, see constructors) -- The amount the size can vary from the base size (see Size Settings in Inputs Guide).

• uint8_t trailType -- The type of trails used for the drops (see Trail Settings in Inputs Guide). Pass in 5 to set the trails randomly between 0, 1, and 2 trails. Pass in 6 to set the trails based on the trail flags.

• uint8_t trailSize -- The length of the rain drop trails (if the particle has them, min val 1).

• uint8_t trailRange (optional, see constructors) -- The amount the trailSize can vary from the base size (see Size Settings in Inputs Guide).

• bool noTrails (optional, default false) -- Used with trailType 6, allows drops with no trails (see Randomizing Trail Types above).

• bool oneTrail (optional, default false) -- Used with trailType 6, allows drops with one trailing trail (see Randomizing Trail Types above).

• bool twoTrail (optional, default false) -- Used with trailType 6, allows drops with two trails (see Randomizing Trail Types above).

• bool revTrail (optional, default false) -- Used with trailType 6, allows drops with one reversed trails (see Randomizing Trail Types above).

• bool infTrail (optional, default false) -- Used with trailType 6, allows drops with infinite trails (see Randomizing Trail Types above).

• uint16_t speed -- The base speed of the drops (ms).

• uint16_t speedRange -- The amount the speed may vary up from the rate (ms) (see Size Settings in Inputs Guide).

• bool direct -- The direction the drops will fall along the segment lines (true is from the first line to last).

• 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.

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

• bool blend (default false) -- Causes rain drops to add their colors to the strip's pixels, rather than set them (see Blend notes in Inputs Guide).

• 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. Warning!: Not compatible with infinite trails (mode 4). They will be drawn over.

• uint16_t spawnBasis (default 1000) -- The default spawn probability threshold. A drop will spawn if random(spawnBasis) <= spawnChance.

• uint16_t* rate-- Update rate (ms). Defaulted to 5ms (see Update note in Inputs Guide). 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.

• 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 setupDrops( uint8_t newMaxNumDrops ); 

  Changes the maximum number of drops. Also calls reset() to reset the drop's spawns. Note that any active drops will be left on the segments. If bgPrefill is true, then the background will be re-filled in the next update to clear them. !!If you change the segment set, you should re-call this function to re-configure the drop particle set!!

• void reset(); 

  Resets the effect by setting all particles to inactive. Configures the background to be cleared on the next update if bgPrefill is true.

• void update();

  Updates the effect.

• uint8_t maxNumDrops -- (see Constructor Inputs above) set using setupDrops().