 |
HitLib 1.5.0
VEX V5 LED animation library for PROS
|
|
HitLib 1.5.0
VEX V5 LED animation library for PROS
|
Every animation below is available on hitlib::LedStrand. Nearly all of them are on hitlib::LedGroup too, where the call fans out to every strand in the group simultaneously; the exceptions are noted where they come up - overlayTwinkle(), overlayBitscroll() and the per-region gauge helpers (motorHeatGauge(), setRegionLevel()) are strand-only, so reach a strand through group[i] for those.
All calls are thread-safe and take effect on the next refresh tick.
Everything below can also be built - and combined, and driven from a sensor - as a custom animation in Pattern Studio's Animate tab. See Custom Animations.
Every animation that moves - flow, rainbow, pulse, bitscroll, and their overlay and splice-region versions - takes a hitlib::LedStrand::Speed. A bare number is pixels per refresh tick, which is what speed has always meant:
A pixel a tick is the slowest a bare number can go. For anything slower, give the time between steps instead:
Like flash()'s durations, the step time is rounded to whole refresh ticks, so the pace stays even: a 100 ms step on a 20 ms strand moves on every fifth tick, never on a mix of fourth and sixth ones. A splice region takes one the same way, as .speed = Speed::everyMs(100).
Generates a gradient between two colors and scrolls it continuously. invert reverses the scroll direction. seamless (default true) loops the gradient back to the first color instead of cutting straight from the second color back to the first at the wrap.
Full HSV rainbow scrolled across the strip.
Blinks the whole strip: every LED lights at once for onMs, then the whole strip shows bgColor for offMs, and the cycle repeats.
On and off times are independent, so blink rate and duty cycle are set separately. 100, 100 is an even 5 Hz blink, while 100, 400 keeps the same brief flash at 2 Hz. Durations are rounded to whole refresh ticks and clamped to a minimum of one tick, so a strand can't be asked to blink faster than its refresh interval (its group's, once it is in a hitlib::LedGroup). They are also capped at 65535 ticks, about 22 minutes at 20 ms, so a huge onMs such as UINT32_MAX stays lit that long rather than wrapping round to one tick.
Randomly spawns sparkles from the palette that fade in, hold briefly, then fade out.
repeating applies to both travel styles: with true the pattern tiles across the whole strip, with false a single copy travels the strip on its own.
A second animation buffer, independent of the base animation. Shown directly in splice mask regions that set useOverlay.
The overlay carries the same vocabulary as the base animations, minus bounce: it is a single scrolling buffer, and bouncing needs a wider master pattern to slide a window over. Use the base animation when you want that.
Fills the strip from one end in proportion to a 0-255 level, and dims the LED at the edge of the fill part-way so a short strand still shows a smooth ramp rather than one step per pixel.
With gradient, the two colors are laid out across the whole strip, not across the lit part, so a given pixel is always the same color no matter how full the meter is, as a VU-style scale needs; a gradient stretched over the fill would recolor every pixel on every update.
Three things can move a meter, and they are mutually exclusive - whichever was set up last owns it, so a strip handed to a song never has a stale sensor fighting it for the same pixels:
| Set up with | Moved by | |
|---|---|---|
| By hand | levelFill() | your code calling setLevel() |
| From a value | levelSource() | the strand, once per tick |
| From a song | musicSync() | the baked envelope, against the wall clock |
levelSource() hands the strand a reader and the range it maps onto the strip. From then on the bar tracks the value with no code in your control loop at all:
The two bounds are in whatever units the reader already speaks - degrees, percent, millimetres, RPM - so nothing has to be scaled into 0-255 first:
Set it up once - in initialize(), or in a mode's onActivate so the meter follows that mode - and call clearLevelSource() or setLevel() to take it back by hand.
A few details worth knowing:
Pattern Studio has this as its Fill animation: pick what the bar follows from a list of the things a V5 robot actually has - battery capacity, motor heat, position, velocity or efficiency, a rotation sensor, an IMU heading, a distance sensor, a potentiometer - and the exported header carries the reader already written, including the #include it needs. Anything not on the list exports as a LevelFn hook to assign from your own code, and the export's banner spells out the assignment.
The same meter, driven by a song instead of by hand.
The V5 can neither hear audio nor decode a song, so it is resolved on the desktop. Pattern Studio reads an audio file - MP3, M4A, FLAC, OGG, WAV - or a MIDI, measures its loudness in three frequency bands, and exports each band a strand uses as a table of one byte per frame. On the robot, playback is an array lookup and a lerp per tick, no matter how long the song is.
Playback is anchored to the wall clock at the moment musicSync() runs, so call it when the music starts, typically from a mode's onActivate. Samples are interpolated between frames, so the fill stays smooth even when the envelope's frame rate is coarser than refreshMs.
Each strand picks the part of the song it follows, so a robot with two strips can run them off one track without them moving together:
| Band | What it follows |
|---|---|
| Bass | Kick and bass. Pumps on the beat, and what most strips want. |
| Mid | Vocals, snare, guitars. Follows the body of the arrangement. |
| Treble | Hats and cymbals. Sparse and sparkly. |
| Full mix | Everything at once. Steadiest, least rhythmic. |
Only the bands a design actually uses are exported, so following the bass alone costs one table rather than four.
A percentage gain applied to every sample: above 100 the quiet passages reach further up the strip (and loud ones clip at full), below 100 only the peaks register. It is the one knob worth retuning on the robot, so it has its own setter and needs no re-export:
Everything about how the song drives the strip - which band, how hard it punches, how fast it falls away - is decided in Pattern Studio and baked into the table. A three-minute song at the default 25 ms frame is about 7 KB of flash per band.
Overrides part of the strip, either as equal alternating bins sharing the overlay buffer (spliceMask) or as arbitrarily placed regions that each animate independently (spliceMaskCustom). The two forms are mutually exclusive - whichever was called most recently is what's active.
SpliceRegionAnimKind has nine values. Each region reads only the fields its kind uses, so the rest can be left at their defaults:
| Kind | Shows | Fields it reads |
|---|---|---|
| OFF | Nothing - the region stays dark. The default. | - |
| SOLID | One flat color. | color |
| PULSE | A run of color travelling over a background. | color, bgColor, runLength, speed |
| FLASH | The whole region blinking on and off. | color, bgColor, onMs, offMs |
| FLOW | A two-color gradient scrolling through the region. | color, color2, speed, seamless |
| RAINBOW | A full HSV rainbow across the region. | speed |
| TWINKLE | Sparkles drawn from a palette. | palette, densityPct, fadeStep, bgColor |
| BITSCROLL | Evenly sized runs scrolling through the region. | color, bgColor, segmentWidth, spacing, repeating, speed, invert |
| GAUGE | A meter colored off its own scale. See below. | read, emptyAt, fullAt, wrap, smoothing, stops, style, blend, bgColor, invert |
invert is narrower here than on the base animations: it reverses a BITSCROLL's scroll direction and picks which end a GAUGE BAR fills from, and every other kind ignores it. There is no bounce at all - a region scrolls a buffer its own width, and bouncing needs a wider master pattern to slide a window over.
Regions animate on their own clocks, so a FLASH region and a BITSCROLL region in the same mask do not have to agree on a period. A region's BITSCROLL takes a single segmentWidth rather than the base animation's list of BitScrollSegments, since a region is usually only a few pixels wide. SOLID and OFF cost nothing per tick: neither one allocates a buffer.
A GAUGE region is the odd one out: it animates from a reading rather than from a clock. Each one polls its own value every tick and colors itself off its own scale, so a single strip can carry several independent meters – which the strand-wide level meter cannot do, there being one of those per strand.
The scale is a list of stops given in the reading's own units, so it says what it means. Below the first stop and above the last, the gauge holds that stop's color, so a scale never has to cover a range you don't care about. Two stops at the same reading make a hard edge: the one listed first is the color below it, the second the color above. stops is optional: leave it empty and the gauge falls back to color at emptyAt blending to color2 at fullAt, so a plain two-color gauge needs no scale at all.
style picks what the region does with its level: HEAT (the default) colors every pixel it owns at once, and BAR fills the region proportionally instead, like a miniature levelFill(). blend picks what happens between two stops: LERP slides between their colors, and STEP holds each one until the next is actually reached – the honest choice when the stops are thresholds something crosses rather than points on a ramp. A reading exactly on a stop has reached it, which matters for a V5 motor: it reports temperature in 5 C steps that land right on the motor heat scale's stops.
Leave read as nullptr and the region is hand-driven instead, through setRegionLevel() – setLevel()'s counterpart for one region.
The case gauges exist for: a strip under the drivebase, split into one segment per motor, each colored by how hot its own motor is. motorHeatGauge() is a gauge region arriving pre-loaded with the V5's own derating schedule, so the colors mean something specific rather than being a pretty ramp – green cold, yellow nearing the first cut, then orange, red and deep red for the 50%, 25% and 12.5% current limits, and magenta at 70 °C where the motor shuts down.
The V5 reports motor temperature in coarse steps rather than as a continuous reading, which is why the preset ships with smoothing at 80: without it a segment jumps from one stop color straight to the next instead of creeping between them.
Pattern Studio builds the whole thing without any of this being typed: set one region up as a Gauge on Motor Temperature (which brings the six stops with it), then press Divide to lay out however many equal segments the strip holds and change each one's port.
1.16.1