Skip to content

RgbwColor object API

Jump to bottom Edit New page
Michael Miller edited this page Jul 5, 2023 · 9 revisions

RgbwColor represents a color object that is represented by Red, Green, Blue, and White component values. Its primary use is to contain and manipulate colors for 4 element Pixels.

Properties

There are four properties that represent the component values Red, Green, Blue, and White. The values range from 0 to 255. Black would 0,0,0,0 and white using the color LEDs would be 255,255,255,0 and white using the white LED would be 0,0,0,255.

uint8_t R;
uint8_t G;
uint8_t B;
uint8_t W;

There are also a few constant properties that are helpful to use. These are..

Max

The highest value for a single color element.

    const static uint16_t Max = 255;

Count

The number of color elements. Useful when accessing the elements using the [] operators.

    const static size_t Count = 4;

Constructors

RgbwColor(uint8_t r, uint8_t g, uint8_t b, uint8_t w) :

Constructs a RgbwColor using Red, Green, Blue, and White component values.

  • r - value for the Red component (0 - 255)
  • g - value for the Green component (0 - 255)
  • b - value for the Blue component (0 - 255)
  • w - value for the White component (0 - 255)

RgbwColor(uint8_t brightness)

Constructs a RgbwColor using a single brightness value(0 - 255). This works well for creating gray tone colors.

  • brightness - value for the white component where (0) = black, (128) = gray, (255) = white.
    This will only affect the W color element.

RgbwColor(RgbColor color);

Construct a RgbwColor using RgbColor, copying the R,G,B values and setting W to zero.

  • color - a RgbColor object.

RgbwColor(HslColor color);

Construct a RgbwColor using HslColor, converting the Hsl to Rgbw

  • color - a HslColor object.

RgbwColor(HsbColor color);

Construct a RgbwColor using HsbColor, converting the Hsb to Rgbw

  • color - a HsbColor object.

RgbwColor()

Construct a RgbwColor that will have its values set in latter operations.
CAUTION: The R,G,B,W members are not initialized and may not be consistent until set.

Methods

uint8_t CalculateBrightness();

CalculateBrightness will calculate the overall brightness.
NOTE: For color objects with only W set, it will return W. For color objects with W set to zero this is a simple linear brightness. For color objects with values in W and another color component, the overall brightness is the brighter of the color components and the W.

RgbwColor Dim(uint8_t ratio);

Dim will return a new color that is blended to black with the given ratio.
NOTE: This is a simple linear change.

  • ratio - (0-255) where 255 will return the original color and 0 will return black.

RgbwColor Brighten(uint8_t ratio);

Brighten will return a new color that is blended to white with the given ratio.
NOTE: This is a simple linear change.

  • ratio - (0-255) where 255 will return the original color and 0 will return white.

void Darken(uint8_t delta);

Darken will adjust the color by the given delta toward black.
NOTE: This is a simple linear change.

  • delta - (0-255) the amount to dim the color by.

void Lighten(uint8_t delta);

Lighten will adjust the color by the given delta toward white.
NOTE: This is a simple linear change. If the color only has W value set, only W will be modified; otherwise only the R,G,B will be modified leaving W alone.

  • delta - (0-255) the amount to lighten the color by.

int16_t CompareTo(const RgbwColor& other, uint8_t epsilon = 1)

Compares against another color with the given epsilon.
Returns the greatest difference of a set of elements, where 0 means the colors are equal within epsilon delta, negative means this is less than the other, positive means this is greater than the other.

  • other - the color to compare against.
  • epsilon - the max delta acceptable for them to be considered the same color.

static int16_t Compare(const RgbwColor& left, const RgbwColor& right, uint8_t epsilon = 1)

Compares two colors with the given epsilon.
Returns the greatest difference of a set of elements, where 0 means the colors are equal within epsilon delta, negative means left is less than the right, positive means left is greater than the right.

  • left - the first color to compare.
  • right - the other color to compare.
  • epsilon - the max delta acceptable for them to be considered the same color.

static RgbwColor LinearBlend(RgbwColor left, RgbwColor right, float progress);

This will blend between two colors by the amount defined by the progress variable.

  • left - the color to start the blend at.
  • right - the color to end the blend at.
  • progress - (0.0f - 1.0f) value where 0.0f will return left and 1.0f will return right and a value between will blend the color weighted linearly between them.
    This is a static function, which means you need to call it scoped to the object class and not an instance like...
    RgbwColor results = RgbwColor::LinearBlend(RgbwColor(255,0,0,0), RgbwColor(0,255,0,10), 0.33f);

static RgbwColor LinearBlend(RgbwColor left, RgbwColor right, uint8_t progress);

This will blend between two colors by the amount defined by the progress variable.

  • left - the color to start the blend at.
  • right - the color to end the blend at.
  • progress - (0 - 255) value where 0 will return left and 255 will return right and a value between will blend the color weighted linearly between them.
    This is a static function, which means you need to call it scoped to the object class and not an instance like...
    RgbwColor results = RgbwColor::LinearBlend(RgbwColor(255,0,0,0), RgbwColor(0,255,0,10), 85);

static RgbwColor BilinearBlend(RgbwColor c00, RgbwColor c01, RgbwColor c10, RgbwColor c11, float x, float y);

This will blend between four colors by the amount defined by 2d weighting values.

  • c00 - upper left quadrant color
  • c01 - upper right quadrant color
  • c10 - lower left quadrant color
  • c11 - lower right quadrant color
  • x - unit value (0.0 - 1.0) that defines the blend progress in horizontal space
  • y - unit value (0.0 - 1.0) that defines the blend progress in vertical space

Operators

uint8_t operator[](size_t idx)

The index operator allows accessing the R, G, B, and W properties using an index. There are both read only and read write versions.

   uint8_t white = color[3];

You can also use the color index constants.

   uint16_t white = color[ColorIndexW];
Add a custom footer
Clone this wiki locally