diff --git a/T_GAMMA.md b/T_GAMMA.md new file mode 100644 index 0000000..eb41fb5 --- /dev/null +++ b/T_GAMMA.md @@ -0,0 +1,52 @@ +The T_GAMMA is a template class specialization feature that defines the specifics of the model used to adjust the colors for gamma output of the LEDs being used. The human eye perceives light levels differently than what the NeoPixels/DotStars show. NeoPixels brightness levels are very linear, so this object will convert them to the nonlinear so that what you see is what you expected. +You as the sketch author do not need to write one of these as a library of them is available for you to choose from. If you need something custom then you can write your own, just copy one of the following and modify as you see fit. + +### NeoGammaEquationMethod +If not specified this is the default used. It uses an equation to calculate the gamma correction. It is slower but more accurate. +``` +NeoPixelBusLg strip(PixelCount, PixelPin); +``` + +### NeoGammaCieLabEquationMethod +Like the NeoGammaEquationMethod but uses as a specific model by the CIE Lab. It is slower but more accurate. +``` +NeoPixelBusLg strip(PixelCount, PixelPin); +``` + +### NeoGammaTableMethod +This will use a pre-calculated static lookup table to improve performance. This consumes memory to contain the lookup table. While just as accurate when using 8-bit color elements, the accuracy is not as good when using 16-bit color elements. +``` +NeoPixelBusLg strip(PixelCount, PixelPin); +``` + +### NeoGammaDynamicTableMethod +This will use sketch defined equation to dynamically create at runtime the pre-calculated lookup table to improve performance. This consumes memory to contain the lookup table. While just as accurate when using 8-bit color elements, the accuracy is not as good when using 16-bit color elements. +Using this specialization object will require that you provide a callback function that will calculate the gamma and that in setup() of your sketch that you call NeoGammaDynamicTableMethod::Initialize(yourGammaCalcFunction). + +``` +NeoPixelBusLg strip(PixelCount, PixelPin); + +float GammaCalc(float unitValue) { + // we will use CieLab gamma equation for our custom table + return NeoEase::GammaCieLab(unitValue); +} + +setup() { + NeoGammaDynamicTableMethod::Initialize(GammaCalc); + strip.Begin(); +} +``` +In the NeoPixelGammaDynamic example you can see a demonstration of how it used with a normal NeoPixelBus strip. + +### NeoGammaNullMethod +This will cause no gamma correction to be applied. Use this as way to disable gamma correction. +``` +NeoPixelBusLg strip(PixelCount, PixelPin); +``` + +### NeoGammaInvert +In the rare case that your NeoPixels have values that are inverted where it thinks 0 is full bright and 255 is black; you can use this wrapping specialization class to invert the colors at the last stage of pixel adjustments. +Below demonstrates the construction of a NeoPixelBusLg object using an inverted NeoGammaTableMethod for gamma specialization. +``` +NeoPixelBusLg> strip(PixelCount, PixelPin); +```