color.lua

Introduction

color.lua offers a way to manage colors as objects, allowing you to combine, interpolate and convert colors from/to other color spaces such as HSL and HSV.

Example

local Color = require "grove.color"

local myColor = Color(1, 1, 0, 1) -- Yellow
local myColor2 = Color("#ff7f7f7f") -- Gray

function love.draw()
    love.graphics.setColor(myColor) -- You can pass color objects directly to setColor()
    love.graphics.rectangle("fill", 10, 10, 50, 50)


    local myColor3 = myColor * myColor2 -- dark yellow
    local text = ("H: %f, S: %f, L: %f"):format(myColor3.h, myColor3.s, myColor3.l)
    love.graphics.setColor(myColor3)
    love.graphics.print(text, 80, 10)


    local myColor4 = Color.CYAN
    myColor4.lightness = 0.2

    love.graphics.setColor(myColor4)
    love.graphics.circle("fill", 100, 100, 30)
end

Functions

Constructors

Color()

Create a white color object.

---

Color(r, g, b a)

Create a color object and initialize it with a custom RGBA value.

r (number): The initial red component. Range: 0-1.
g (number): The initial green component. Range: 0-1.
b (number): The initial blue component. Range: 0-1.
a (number): The initial alpha component. Range: 0-1.

---

Color(hex)

Create a color object and initialize it with a HEX color.

hex (string or number): The color represented as string (ex: "#FFFFFFFF") or as number (ex: 0xFFFFFFFF). The color must be in the AARRGGBB format.

---

Object fields

object.r

object.red

Get/set the red component. Range: 0-1.

---

object.g

object.green

Get/set the green component. Range: 0-1.

---

object.b

object.blue

Get/set the blue component. Range: 0-1.

---

object.h

object.hue

Get/set the hue component. Range: 0-359.

---

object.s

object.saturation

Get/set the saturation component (HSL). Range: 0-1

---

object.l

object.lightness

Get/set the lightness component (HSL). Range: 0-1

---

object.ss

object.ssaturation

Get/set the saturation component (HSV). Range: 0-1

---

object.v

object.value

Get/set the value component (HSV). Range: 0-1

---

object.hex

Get/set the color with a hex string/number.

---

Object arithmetic

object1 + object2

object1 - object2

object1 * object2

object1 / object2

Performs a arithmetic operation between every RGBA component of the two objects and returns a new color object with the result.

---

object + number

object - number

object * number

object / number

Performs a arithmetic operation between number and every RGBA component of object and returns a new color object with the result.

---

object ^ number

Returns a clone of the object with the hue shifted to number degrees. The hue will wrap between 0 and 359.

---

-object

Returns a clone of the object with the RGB components inverted. The alpha component will remain unchanged.

---

Object methods

object:setRGBA(r, g, b a)

Set the current color using the RGBA format.

r (number): The red component. Range: 0-1.
g (number): The green component. Range: 0-1.
b (number): The blue component. Range: 0-1.
a (number): The alpha component. Range: 0-1.

---

object:setByteRGBA(r, g, b a)

Set the current color using the RGBA format, but with the components in bytes.

r (number): The red component. Range: 0-255.
g (number): The green component. Range: 0-255.
b (number): The blue component. Range: 0-255.
a (number): The alpha component. Range: 0-255.

---

object:setHSL(h, s, l)

Set the current color using the HSL format.

h (number): The hue component. Range: 0-359.
s (number): The saturation component. Range: 0-1.
l (number): The lightness component. Range: 0-1.

---

object:setHSV(h, s, v)

Set the current color using the HSV format.

h (number): The hue component. Range: 0-359.
s (number): The saturation component. Range: 0-1.
v (number): The value component. Range: 0-1.

---

object:add(other)

object:subtract(other)

object:multiply(other)

object:divide(other)

object:shiftHue(deg)

object:invert()

Does the same as +, -, *, ^ and -object operators, but the results are applied in object instead of creating a new one.

---

object:getRGBA()

Returns the r, g, b and a components.

---

object:getByteRGBA()

Returns the r, g, b and a components in bytes.

---

object:getHSL()

Returns the h, s and l components.

---

object:getHSV()

Returns the h, ss and v components.

---

object:clone()

Creates a new color object with the same color of the current object.

---

Module utils

Color.lerp(from, to, progress)

Interpolates between two colors and returns a new color object with the result.

from (color): The initial color.
to (color): The target color.
progress (number): The interpolation amount. Range: 0-1.

---

Color.distance(a, b)

Calculates the distance between two colors.

a (color): The first color.
b (color): The second color.

---

Color.HSVtoRGB(h, s, v)

Converts a HSV color to RGB. The result is returned as numbers instead of a color object.

h (number): The hue component. Range: 0-359.
s (number): The saturation component. Range: 0-1
v (number): The value component. Range: 0-1

---

Color.RGBtoHSV(r, g, b)

Converts a RGB color to HSV. The result is returned as numbers instead of a color object.

r (number): The red component. Range: 0-1.
g (number): The green component. Range: 0-1.
b (number): The blue component. Range: 0-1

---

Color.HSLtoRGB(h, s, l)

Converts a HSL color to RGB. The result is returned as numbers instead of a color object.

h (number): The hue component. Range: 0-1.
s (number): The saturation component. Range: 0-1.
l (number): The lightness component. Range: 0-1.

---

Color.RGBtoHSL(r, g, b)

Converts a RGB color to HSL. The result is returned as numbers instead of a color object.

r (number): The red component. Range: 0-1.
g (number): The green component. Range: 0-1.
b (number): The blue component. Range: 0-1

---

Color.HEXtoRGBA(hex)

Converts a hex color to RGBA. The result is returned as numbers instead of a color object.

hex (string or number): The color represented as string (ex: "#FFFFFFFF") or as number (ex: 0xFFFFFFFF). The color must be in the AARRGGBB format.

---

Color.RGBAtoHEX(r, g, b, a)

Converts a RGBA color to HEX. The result is returned as string instead of a color object.

r (number): The red component. Range: 0-1.
g (number): The green component. Range: 0-1.
b (number): The blue component. Range: 0-1

---

Color.validateHEX(hex)

Checks if the HEX color string is valid.

hex (string): The HEX string to check.

---

Predefined colors

color.lua also offers a way to create a new color object initialized with a known color.

local blue = Color.BLUE
local darkGreen = Color.DARK_GREEN

Here's a list of all predefined colors available:

Color	HEX
BLACK	#FF000000
WHITE	#FFFFFFFF
RED	#FFFF0000
GREEN	#FF00FF00
BLUE	#FF0000FF
YELLOW	#FFFFFF00
GRAY	#FF808080
CYAN	#FF00FFFF
MAGENTA	#FFFF00FF
AQUA	#FF00FFFF
BROWN	#FFA52A2A
PINK	#FFFFC0CB
CORAL	#FFFF7F50
CRIMSON	#FFDC143C
DARK_BLUE	#FF00008B
DARK_CYAN	#FF008B8B
DARK_GRAY	#FFA9A9A9
DARK_GREEN	#FF006400
DARK_RED	#FF8B0000
GOLD	#FFFFD700
IVORY	#FFFFFFF0
LIME	#FF00FF00
PURPLE	#FF800080