Makuna/NeoPixelBus
1
0
Fork 1
mirror of https://github.com/Makuna/NeoPixelBus.git synced 2025-08-10 14:24:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Updated NeoPixelAnimator object (markdown)

Michael Miller
2016-04-23 10:55:05 -07:00
parent 4ea896453b
commit a4f7eb145c
1 changed files with 43 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
NeoPixelAnimator-object.md

@@ -1,20 +1,23 @@
[NeoPixelAnimator object API](https://github.com/Makuna/NeoPixelBus/wiki/NeoPixelAnimator-object-API) [NeoPixelAnimator object API](https://github.com/Makuna/NeoPixelBus/wiki/NeoPixelAnimator-object-API)
The NeoPixelAnimator manages the timing and lifetime for animations. It does not provide specific animations effects, as these are varied and specific to the application and left for you to create. The NeoPixelAnimator manages the timing and lifetime for animations. It does not provide specific animations effects, as these are varied and specific to the application and left for you to create.
A single animation is managed by a Animation Channel. An animation channel contains the duration of the animation, the progress in that duration as the animation runs, and the method to call to actually calculate and apply any changes to the NeoPixelBus. A single animation is managed by a Animation Channel. An animation channel contains the duration of the animation, the progress in that duration as the animation runs, and the method to call to actually calculate and apply any changes to the NeoPixelBus.
The NeoPixelAnimator manages these channels and the total number it can manage is defined at construction time. The NeoPixelAnimator manages these channels and the total number it can manage is defined at construction time.
It manages them by periodically comparing real time to the animation duration and progress and calling the update function with the state of the animation. It does this when your code calls the UpdateAnimations(). It manages them by periodically comparing real time to the animation duration and progress and calling the update function with the state of the animation. It does this when your code calls the `UpdateAnimations()`.
All time values are by default in milliseconds but this can be changed to manage long duration animations as well. All time values are by default in milliseconds but this can be changed to manage long duration animations as well.
NOTE: NeoPixelBus::Show() must still be called to push the color state to the physical NeoPixels. Usually this is done right after calling NeoPixelAnimator::UpdateAnimations() in the main Loop() function. NOTE: `Show()` must still be called to push the color state to the physical NeoPixels. Usually this is done right after calling `UpdateAnimations()` in the main `Loop()` function.
## Getting Started ## Getting Started
For each animation you start, you will need to provide a function that will "apply" the animation with the given progress. The function will be called with a AnimationParam structure which contains three properties about the animation to update, with the important one being the unit progress (0.0 to 1.0). For each animation you start, you will need to provide a function that will "apply" the animation with the given progress. The function will be called with a `AnimationParam` structure which contains three properties about the animation to update, with the important one being the unit progress (0.0 to 1.0).
To "apply" an animation takes several small pieces of code: To "apply" an animation takes several small pieces of code:
First, apply an optional curve to the AnimationParam.progress. This progress is a linear time value from 0.0f at the start of the animation to 1.0f at the end of the animation. The term "linear time" means that progress will map 1:1 to real time. This progress is an abstraction from real time so that the update routine can use common methods to manipulate this progress and apply it to the values that need to be modified. #### First, apply an optional curve to the `AnimationParam.progress`.
Sometimes what you want is to simulate "mass" so that the animation feels like it starts slow but ends up faster. To do this, we just modify the given progress by using a curve equation that will "ease-in", "ease-out", or "ease in and out". These functions maintain the range of 0.0 to 1.0 but will modify the results to apply a curve. Now the new value can be used instead. More on this subject below in the easing section. This progress is a linear time value from 0.0f at the start of the animation to 1.0f at the end of the animation. The term "linear time" means that progress will map 1:1 to real time. This progress is an abstraction from real time so that the update routine can use common methods to manipulate this progress and apply it to the values that need to be modified.
Sometimes what you want is to simulate "mass" so that the animation feels like it starts slow but ends up faster. To do this, we just modify the given progress by using a curve equation that will "ease-in", "ease-out", or "ease in and out". These functions maintain the range of 0.0 to 1.0 but will modify the results to apply a curve. Now the new value can be used instead. More on this subject below in the [easing section](https://github.com/Makuna/NeoPixelBus/wiki/NeoPixelAnimator-object#easing-equations).
``` ```
void UpdateAnim(AnimationParam param) void UpdateAnim(AnimationParam param)
{ {
@@ -24,7 +27,9 @@ void UpdateAnim(AnimationParam param)
} }
``` ```
Second, use the progress to effect the animation. The animation maybe just moving one lit pixel along a strip of pixels, or it maybe blending from one color to another. Most interpolation functions will take this progress directly as they expect a 0.0 to 1.0 value. You can find interpolation functions for most properties you want to animation, like colors or even coordinates. The color objects provided in this library contain blend functions that can be used directly. Implementing your own is simple also. LERP is short for Linear Interpolation and you may have good success in using this term to find routines you need. More on this subject below in the lerp section. #### Second, use the progress to effect the animation.
The animation maybe just moving one lit pixel along a strip of pixels, or it maybe blending from one color to another. Most interpolation functions will take this progress directly as they expect a 0.0 to 1.0 value. You can find interpolation functions for most properties you want to animate, like colors or even coordinates. The color objects provided in this library contain blend functions that can be used directly. Implementing your own is simple also.
NOTE: LERP is short for Linear Interpolation and you may have good success in using this term to find routines you need from your favorite search engine. More on this subject below in the [lerp section](https://github.com/Makuna/NeoPixelBus/wiki/NeoPixelAnimator-object#lerp---linear-interpolation).
``` ```
void UpdateAnim(AnimationParam param) void UpdateAnim(AnimationParam param)
@@ -37,7 +42,8 @@ void UpdateAnim(AnimationParam param)
} }
``` ```
Lastly, apply the changes to the NeoPixelBus. Usually you will just call SetPixelColor somewhere in the animation update function; but you won't call NeoPixelBus::Show() as that is always left in the Loop(). #### Lastly, apply the changes to the NeoPixelBus.
Usually you will just call `SetPixelColor()` somewhere in the animation update function; but you won't call `Show()` as that is always left in the `Loop()`.
``` ```
void UpdateAnim(AnimationParam param) void UpdateAnim(AnimationParam param)
@@ -51,7 +57,7 @@ void UpdateAnim(AnimationParam param)
} }
``` ```
To keep the NeoPixelAnimator running, you will need to call UpdateAnimations() in the Loop() of the sketch. Usually you will follow it with a Show() like this. To keep the NeoPixelAnimator running, you will need to call `UpdateAnimations()` in the `Loop()` of the sketch. Usually you will follow it with a `Show()` like this.
``` ```
void loop() void loop()
{ {
@@ -62,39 +68,39 @@ void loop()
## Easing equations ## Easing equations
Most easing equations are grouped by three basic types. Most easing equations are grouped by three basic types.
Ease In - Calculates a progress that is accelerating from a complete stop with no velocity. * Ease In - Calculates a progress that is accelerating from a complete stop with no velocity.
Ease Out - Calculates a progress that is decelerating toward a complete stop. * Ease Out - Calculates a progress that is decelerating toward a complete stop.
Ease In/Out - Calculates a progress that is accelerating from a complete stop until the halfway point at which time it then decelerates toward a complete stop at the end. * Ease In/Out - Calculates a progress that is accelerating from a complete stop until the halfway point at which time it then decelerates toward a complete stop at the end.
In the NeoEase class you will find a whole series of these functions; each with a different curve. A great place to see them visualized is at [Gizam.com Easing](http://www.gizma.com/easing). In the NeoEase class you will find a whole series of these functions; each with a different curve. A great place to see them visualized is at [Gizam.com Easing](http://www.gizma.com/easing).
This first set are basically similar curve shapes but with more pronounced acceleration as you progress down the list. This first set are basically similar curve shapes but with more pronounced acceleration as you progress down the list.
QuadraticIn * QuadraticIn
QuadraticOut * QuadraticOut
QuadraticInOut * QuadraticInOut
CubicIn * CubicIn
CubicOut * CubicOut
CubicInOut * CubicInOut
QuarticIn * QuarticIn
QuarticOut * QuarticOut
QuarticInOut * QuarticInOut
QuinticIn * QuinticIn
QuinticOut * QuinticOut
QuinticInOut * QuinticInOut
SinusoidalIn * SinusoidalIn
SinusoidalOut * SinusoidalOut
SinusoidalInOut * SinusoidalInOut
ExponentialIn * ExponentialIn
ExponentialOut * ExponentialOut
ExponentialInOut * ExponentialInOut
The following equations have a more circular shape to the curve. They have a much more dramatic ease at the end. The following equations have a more circular shape to the curve. They have a much more dramatic ease at the end.
CircularIn * CircularIn
CircularOut * CircularOut
CircularInOut * CircularInOut
This easing equation is specific to animating through a gamma corrected color. This easing equation is specific to animating through a gamma corrected color.
Gamma * Gamma
## LERP - Linear Interpolation ## LERP - Linear Interpolation
To interpolate between two values using a 0.0 to 1.0 progress value is a simple equation. To interpolate between two values using a 0.0 to 1.0 progress value is a simple equation.
@@ -102,4 +108,6 @@ To interpolate between two values using a 0.0 to 1.0 progress value is a simple
v0 = value that is returned when the progress is zero v0 = value that is returned when the progress is zero
v1 = value that is returned when the progress is one v1 = value that is returned when the progress is one
progress = a floating point value between 0.0 and 1.0 also referred to as time. progress = a floating point value between 0.0 and 1.0 also referred to as time.
```
lerp = (v1 - v0) * progress + v0; lerp = (v1 - v0) * progress + v0;
```