<commit_before>FastFader
=================

This is an [Arduino](http://arduino.cc/) library that implements a fast cross-fader and pixel buffer for use with LED lighting strips. It pairs with the [FastLED library](http://fastled.io/) to produce smooth, fast animations on WS2810, WS2811, LPD8806, Neopixel and [other types of lighting strips](https://github.com/FastLED/FastLED/wiki/Chipset-reference).

Prerequisites
-------------

Since this needs to use the `math.h` library, you will need an [Arduino ATmega168](http://arduino.cc/en/Hacking/PinMapping168) or better CPU. You will also need to have the [FastLED](https://github.com/FastLED/FastLED/) library installed.

Installation
------------

To install this library, checkout this codebase and place the FastFader folder next to the FastLED folder in your Arduino Libraries folder. This will usually be in an Arduino folder wherever your operating system keeps documents. Restart the Arduino IDE, and you're ready to go.

Once this library is installed, you'll need to include it in the header of the `.ino` file for the relevant Arduino sketch. The best place for it will be directly below your `#include` directive for FastLED:

```cpp
#include "FastLED.h"    // https://github.com/FastLED/FastLED
#include "FastFader.h"  // https://github.com/danndalf/fastfader

// How many LEDs are in the strip
#define NUM_LEDS 18

// Using the Arduino Uno in dev mode
#define DATA_PIN 2
#define CLOCK_PIN 3

//...
```

Next, where you initialize your LED strip, you'll also need to initialize a fader, then bind them. This should be in your `void setup();` function:

```cpp
/* 
==========================================
= setup()
= Initializes needed variables and drivers, called by Arduino once during initialization.
*/
void setup() {
  // Initialize the LED interface
  FastLED.addLeds<LPD8806, DATA_PIN, CLOCK_PIN, RGB>(leds, NUM_LEDS);

  // Bind the pixel fader to the LED interface
  pixel_fader.bind(pixel_buffer, leds, NUM_LEDS, FastLED);

}
```

Easy as pie.

Usage
-----

To see example lighting demonstrations, check out the `examples` folder of this codebase.

Once you have a fader object instantiated and bound to your FastLED interface, you have the following additional functions available with which to communicate with your LED strip:

### FastFader& clear();

The `fader.clear` function quickly resets the LED strip.

### FastFader& set_pixel(int pos, int value, int channel);
### FastFader& set_pixel(int pos, int value[3]);
### FastFader& set_pixel(int pos, int value);
### FastFader& set_pixel(int pos);

The `fader.set_pixel` function sets an individual pixel by position, value, and channel. Value and Channel are optional arguments. If you call `set_pixel` with no channel, it defaults to all three (Red, Green, and Blue). If you call `set_pixel` with no channel and no value, it assumes a value of 255. Value can be passed as a three-dimensional integer array, or as a single integer (to apply to all three channels).

Any data passed to `set_pixel` that's outside of valid ranges will be clipped.

### int* get_pixel(int pos);

The `fader.get_pixel` function returns a three-dimensional integer array of the present red, green, and blue channel values at a given position.

### FastFader& set_frame(int (*frame)[3]);

The `fader.set_frame` function loads an entire array of pixels into your light strip at once. Its dimensions should match the length of your strip.

Any data passed to `set_frame` that's outside of valid ranges will be clipped.

### FastFader& push(int fader_delay, int fader_steps, int decay_type);
### FastFader& push(int fader_delay, int fader_steps);
### FastFader& push(int fader_delay);
### FastFader& push();

The `fader.push` function sends data to the LED strip through a cross-fader and ditherer. The first two parameters control the timing of the cross-fade. `fader_delay` tells it how many miliseconds to take for the fade, and the `fader_steps` parameter tells it how many divisions of color-space to traverse on its way to the new frame.

Further, three types of cross-fading are supported:

* `NO_DECAY` will disable cross-fading. This is very fast and can be used in parts of a demonstration where CPU-intensive work is happening behind the scenes.
* `LINEAR_DECAY` will cause the new frame to fade in directly: for every step the new frame takes forward, the old frame takes one step back. This is slower, but visually nice.
* `LOGARITHMIC_DECAY` will logarithmically weight the fade-in, since human perception of luminosity is logarithmic, not linear. This is the slowest, but also the prettiest (which is why it's the default).

Any of these three parameters can be passed to `fader.push` as the third parameter.

Maintenance
-----------
<commit_msg>Clarifying push() documentation<commit_after>FastFader
=================

This is an [Arduino](http://arduino.cc/) library that implements a fast cross-fader and pixel buffer for use with LED lighting strips. It pairs with the [FastLED library](http://fastled.io/) to produce smooth, fast animations on WS2810, WS2811, LPD8806, Neopixel and [other types of lighting strips](https://github.com/FastLED/FastLED/wiki/Chipset-reference).

Prerequisites
-------------

Since this needs to use the `math.h` library, you will need an [Arduino ATmega168](http://arduino.cc/en/Hacking/PinMapping168) or better CPU. You will also need to have the [FastLED](https://github.com/FastLED/FastLED/) library installed.

Installation
------------

To install this library, checkout this codebase and place the FastFader folder next to the FastLED folder in your Arduino Libraries folder. This will usually be in an Arduino folder wherever your operating system keeps documents. Restart the Arduino IDE, and you're ready to go.

Once this library is installed, you'll need to include it in the header of the `.ino` file for the relevant Arduino sketch. The best place for it will be directly below your `#include` directive for FastLED:

```cpp
#include "FastLED.h"    // https://github.com/FastLED/FastLED
#include "FastFader.h"  // https://github.com/danndalf/fastfader

// How many LEDs are in the strip
#define NUM_LEDS 18

// Using the Arduino Uno in dev mode
#define DATA_PIN 2
#define CLOCK_PIN 3

//...
```

Next, where you initialize your LED strip, you'll also need to initialize a fader, then bind them. This should be in your `void setup();` function:

```cpp
/* 
==========================================
= setup()
= Initializes needed variables and drivers, called by Arduino once during initialization.
*/
void setup() {
  // Initialize the LED interface
  FastLED.addLeds<LPD8806, DATA_PIN, CLOCK_PIN, RGB>(leds, NUM_LEDS);

  // Bind the pixel fader to the LED interface
  pixel_fader.bind(pixel_buffer, leds, NUM_LEDS, FastLED);

}
```

Easy as pie.

Usage
-----

To see example lighting demonstrations, check out the `examples` folder of this codebase.

Once you have a fader object instantiated and bound to your FastLED interface, you have the following additional functions available with which to communicate with your LED strip:

### FastFader& clear();

The `fader.clear` function quickly resets the LED strip.

### FastFader& set_pixel(int pos, int value, int channel);

AKA:

* `FastFader& set_pixel(int pos, int value[3]);` (takes an array of r, g, and b values)
* `FastFader& set_pixel(int pos, int value);` (pushes a single value to r, g, and b channels)
* `FastFader& set_pixel(int pos);` (turns on a single pixel to fullbrightness)

The `fader.set_pixel` function sets an individual pixel by position, value, and channel. Value and Channel are optional arguments. If you call `set_pixel` with no channel, it defaults to all three (Red, Green, and Blue). If you call `set_pixel` with no channel and no value, it assumes a value of 255. Value can be passed as a three-dimensional integer array, or as a single integer (to apply to all three channels).

Any data passed to `set_pixel` that's outside of valid ranges will be clipped.

### int* get_pixel(int pos);

The `fader.get_pixel` function returns a three-dimensional integer array of the present red, green, and blue channel values at a given position.

### FastFader& set_frame(int (*frame)[3]);

The `fader.set_frame` function loads an entire array of pixels into your light strip at once. Its dimensions should match the length of your strip.

Any data passed to `set_frame` that's outside of valid ranges will be clipped.

### FastFader& push(int fader_delay, int fader_steps, int decay_type);

AKA:

* `FastFader& push(int fader_delay, int fader_steps);` (assumes LOGARITHMIC_DECAY)
* `FastFader& push(int fader_delay);` (assumes ten cross-fade steps)
* `FastFader& push();` (assumes ten cross-fade steps over 100 miliseconds)

The `fader.push` function sends data to the LED strip through a cross-fader and ditherer. The first two parameters control the timing of the cross-fade. `fader_delay` tells it how many miliseconds to take for the fade, and the `fader_steps` parameter tells it how many divisions of color-space to traverse on its way to the new frame.

Further, three types of cross-fading are supported:

* `NO_DECAY` will disable cross-fading. This is very fast and can be used in parts of a demonstration where CPU-intensive work is happening behind the scenes.
* `LINEAR_DECAY` will cause the new frame to fade in directly: for every step the new frame takes forward, the old frame takes one step back. This is slower, but visually nice.
* `LOGARITHMIC_DECAY` will logarithmically weight the fade-in, since human perception of luminosity is logarithmic, not linear. This is the slowest, but also the prettiest (which is why it's the default).

Any of these three parameters can be passed to `fader.push` as the third parameter.

Maintenance
-----------

{'fraction_non_alphanumeric': 0.09869494290375204, 'fraction_numerical': 0.006627243066884176, 'mean_word_length': 4.4253318584070795, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3240847', 'n_tokens_mistral': 2879, 'n_tokens_neox': 2732, 'n_words': 1331}