ESPxRGB is an Arduino library of RGB, RGBW, HSV conversion functions and Gamma Correction written in Xtensa assembler for ESP SoCs.
- Why an assembler RGB manipulation library
- Features
- Options and Use
- Versions
- History and References
- License
Looking to use small, low-powered SoCs to drive long strings of LEDs with the optimum speed and power efficiency requires efficient algorythms and code. Assembler is as efficient as you can get. The ESP SoCs are great given their feature set, conectivity, power and price. Plus, they are easy to program.
The assembler itself is contained in GNU-format assembler .S files, and is not inline assembler. The .S files are compiled along with the ESPxRGB.h header when pulled into a project.
ESPxRGB works in the 8-bit RGB/W space. It covers functions supporting:
- RGB to RGBW
- HSV to RGB and RGBW, with a choice of four HSV algorythms
- RGB gamma correction (for normalizing the perception of pulsing luminance)
- RGB chroma correction (for normalizing the perception of luminance across the spectrum)
plus intersections of all the above.
External C headers provide regular Arduino and ESP-IDF code access to the functions.
Drop the library into your ~Arduino/libraries folder and include the ESPxRGB.h header in your project. The library is compiled based on flags in the src/options.h file: The functions are grouped and can be included/excluded in the compiled code as dictated by pre-processor definitions.
The examples folder contains sketches than can test the functions and generate look-up tables used by the code.
- xgamma8 Normalizes the value of a single 8-bit color value
- xgammaarray8 Normalizes a range of 8-bit color values
- xrgbgamma8 Normalizes a set of 8-bit RGB values
- xrgbwgamma8 Normalizes a set of 8-bit RGBW values
- xrgb2rgbw8 RGB to RGBW
- xhsv2rgb8s HSV to RGB using the Spectrum algorythm
- xhsv2rgb8e HSV to RGB using a power efficient function
- xhsv2rgbwt HSV to RGB using a tweaked function aproximating FastLED Rainbow HSV
- xhsv2rgb8w HSV to RGB using a (sine) wave function
- xhsv2rgb8 HSV to RGB default function that points to an above function of your choice.
- xhsv2rgbgamma8 HSV to RGB with gamma correction
- xhsv2rgbwgamma8 HSV to RGB with gamma correction
- xrgb2rgbwgamma8 RGB to RGBW with gamma correction
- 0.1.0 Initial commit and pre-release
I came to write this library after looking into HSV-to-RGB conversion. FastLED was too broad a library to use, and it dictated that FastLED be at the center of whatever you were doing.
I came to use fast_hsv2rgb from Vagrearg: Lots of interesting math and theory on spectrum HSV, with C implementations, and also AVR, which got me thinking of why not an Xtensa version. I tried copying the logic of the AVR in fast_hsv2rgb, and then the C logic, both of which use complex iterative pointer-swapping, but I decided to use a jump table, and then to simplify the whole thing.
The simplest HSV to RGB code out there, I found, is Kasper Kamperman's, with a simple flow through and case at the end. Looking at it, I found I could simplify it a little more by pulling common calculation up out of the case; I then implemented that in Xtensa. Kasper also addressed dimming for luminance normalization.
Reading up on HSV again on Instructables, Ontaelio also looked into power efficiency by using wave forms and in to how they effected percieved color. Both power-efficient (saw-tooth) and smoother looking (sine) wave implementation leverage the spectrum HSV code.
Yet the discussion of more natural looking HSV color-wheels led me to look at FastLED HSV to RGB and at their Rainbow HSV. Not being able to quickly grok the code, looking at the rainbow waveform image led me to implement an approximation of that but at with a code complexity level within my reach :)
ESPxRGB - Copyright 2019 technosf [https://github.com/technosf]
Licensed under the GNU LESSER GENERAL PUBLIC LICENSE, Version 3.0 or greater (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.gnu.org/licenses/lgpl-3.0.en.html
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.