Module color

Functions to parse, convert, and otherwise manage colors.

This module doesn't need to be explicitly loaded as all functions are automatically available in the rtk namespace when loading rtk.

Color Value Formats

Except where indicated, functions and attributes across rtk that take a color value can be specified in one of the following formats:

  1. 'name': the case-insensitive name of a CSS color keyword where alpha is assumed to be 1.0
  2. 'name#aa': the case-insensitive name of a CSS color keyword where alpha specified as a two hexdigit code delimited by a hash
  3. '#rrggbb' : HTML hex style string where alpha is assumed to be 1.0
  4. '#rrggbbaa': HTML hex style string with alpha
  5. {r, g, b}: 3-element table holding red, green, and blue numeric values between 0 and 1.0
  6. {r, g, b, a}: 4-element table, as above plus alpha between 0 and 1.0
  7. A 24-bit packed integer holding red in the low byte, green in the middle byte, and blue in the high byte, and where an alpha of 1.0 is assumed.

While many formats are supported, the above encodings all ultimately refer to colors in the RGB colorspace. Colors in other colorspaces (such as HSL or HSV) can be converted using one of the functions in this module.

Example
-- Creates a text widget with aquamarine color that's translucent (format #2 above)
local t = rtk.Text{'Hello world', color='aquamarine#9c'}

-- Sets the current graphic context to red (format #3 above)
rtk.color.set('#ff0000')

-- Creates a container with a translucent white background (format #4 above)
local c = rtk.Container{bg='#ffffff55'}

-- Clears an image to a burgundy color (format #5 above)
img:clear({0.5, 0, 0.25})

Module API

Fields
rtk.color.names table

read/write

A table that maps CSS color names to HTML-style hex color strings. You can also insert your own custom color names into this table.

Functions
rtk.color.set()

Sets the graphic context to the given color before drawing to a surface set by rtk.pushdest()

rtk.color.rgba()

Decodes a color value into its constituent red, green, blue, and alpha parts

rtk.color.luma()

Returns the relative luminance of the given color

rtk.color.hsv()

Converts a color from RGB(A) to HSV(A) colorspace

rtk.color.hsl()

Converts a color from RGB(A) to HSL(A) colorspace

rtk.color.int()

Converts a color to a 24-bit packed integer

rtk.color.mod()

Modifies a color by applying a multiplier against hue, saturation, value, and alpha

rtk.color.convert_native()

Converts between a REAPER-native numeric color and an OS-native numeric color

rtk.color.flip_byte_order()

Changes the endianness of the given color represented as a 24-bit number

rtk.color.get_reaper_theme_bg()

Gets the background color of the current REAPER theme

rtk.color.get_icon_style()

Determines whether light or dark icons should be used given a background color

rtk.color.hex2rgba()

Converts an HTML-style hex formatted color to RGBA

rtk.color.rgba2hex()

Converts an RGBA color to an HTML-style hex formatted string

rtk.color.int2hex()

Convert a 24-bit packed integer color to an HTML-style hex formatted color string

rtk.color.hsv2rgb()

Converts an HSV(A) color to RGB(A)

rtk.color.hsl2rgb()

Converts an HSL(A) color to RGB(A)

Functions

rtk.color.set(color, amul)

Sets the graphic context to the given color before drawing to a surface set by rtk.pushdest().

Parameters
color (colortype)

the color to set the graphics context to

amul (number or nil)

if not nil, the alpha channel is multiplied by this value

rtk.color.rgba(color)

Decodes a color value into its constituent red, green, blue, and alpha parts.

Although various formats are supported, the given color must be in the RGB colorspace. This function just normalizes any supported color format into its individual channels.

Parameters
color (colortype)

the color value to parse

Return Values
1. (number)

the red channel from 0.0 to 1.0

2. (number)

the green channel from 0.0 to 1.0

3. (number)

the blue channel from 0.0 to 1.0

4. (number)

the alpha channel from 0.0 to 1.0, where 1.0 is assumed if the given color value doesn't provide any alpha channel information.

rtk.color.luma(color, under)

Returns the relative luminance of the given color.

Parameters
color (colortype)

the color whose luminance to calculate

under (colortype or nil)

if the given color has an alpha channel below 1.0 then if this parameter is provided, it describes the color underneath so the luminance returned is calculated over two blended colors

Return Values
(number)

the relative luminance from 0.0 to 1.0

rtk.color.hsv(color)

Converts a color from RGB(A) to HSV(A) colorspace.

The alpha channel is optional and if it's encoded in the supplied color it's simply passed through in the return value.

Parameters
color (colortype)

the color to convert to HSV

Return Values
1. (number)

the hue channel from 0.0 to 1.0

2. (number)

the saturation channel from 0.0 to 1.0

3. (number)

the value (aka brightness) channel from 0.0 to 1.0

4. (number)

the alpha channel from 0.0 to 1.0, which defaults to 1.0 if the given color lacks an alpha channel

rtk.color.hsl(color)

Converts a color from RGB(A) to HSL(A) colorspace.

The alpha channel is optional and if it's encoded in the supplied color it's simply passed through in the return value.

Parameters
color (colortype)

the color to convert to HSL

Return Values
1. (number)

the hue channel from 0.0 to 1.0

2. (number)

the saturation channel from 0.0 to 1.0

3. (number)

the lightness channel from 0.0 to 1.0

4. (number)

the alpha channel from 0.0 to 1.0, which defaults to 1.0 if the given color lacks an alpha channel

rtk.color.int(color, native)

Converts a color to a 24-bit packed integer.

Note that packed values don't include alpha channel information, so if the given color includes an alpha value it is ignored.

Example
-- This example opens a color picker (using the SWS API) starting with red.
-- The 'true' here and below has these two functions convert to and from
-- OS-native integer format.
local ok, color = reaper.GR_SelectColor(0, rtk.color.int('#ff0000', true))
if ok ~= 0 then
   log.info('returned color was %s', rtk.color.int2hex(color, true))
end
Parameters
color (colortype)

the color to modify

native (boolean or nil)

if true, the returned value will be filtered through rtk.color.convert_native()

Return Values
(number)

a 24-bit packed integer with red in the low byte and blue in the high byte

rtk.color.mod(color, hmul, smul, vmul, amul)

Modifies a color by applying a multiplier against hue, saturation, value, and alpha.

The modification occurs in the HSV colorspace. Note that in HSV, modifying value (V) has a side effect on saturation but preserves hue (H). In contrast, in HSL (hue, saturation, lightness), modifying lightness implicitly affects hue.

So this function works in HSV rather than HSL as it's less visually disruptive to have side effects on saturation. But if you need to make changes in the HSL colorspace, use rtk.color.hsl() and rtk.color.hsl2rgb().

Parameters
color (colortype)

the color to modify

hmul (number or nil)

the amount to multiply the hue channel (if nil, no change to hue is made)

smul (number or nil)

the amount to multiply the saturation channel (if nil, no change to saturation is made)

vmul (number or nil)

the amount to multiply the value (brightness) channel (if nil, no change to brightness is made)

amul (number or nil)

the amount to multiply the hue channel (if nil, no change to alpha is made)

Return Values
1. (number)

the modified red channel from 0.0 to 1.0

2. (number)

the modified green channel from 0.0 to 1.0

3. (number)

the modified blue channel from 0.0 to 1.0

4. (number)

the modified alpha channel from 0.0 to 1.0

rtk.color.convert_native(n)

Converts between a REAPER-native numeric color and an OS-native numeric color.

It is necessary to call this function when interacting with non-rtk functions that need to receive OS-native color values, for example reaper.GR_SelectColor().

This function works in both directions, so calling it twice (with the second call receiving the output of the first call) returns the original value.

Note

It's probably more convenient to use rtk.color.int() or rtk.color.int2hex(), both of which take a flag to convert between an OS-native numeric color.

Parameters
n (number)

the numeric color that is either REAPER- or OS-native

Return Values
(number)

the converted color

rtk.color.flip_byte_order(color)

Changes the endianness of the given color represented as a 24-bit number.

Unlike rtk.color.convert_native() that only changes the byte order on platforms that need it (Mac and Linux, specifically), this function always flips the byte order.

This is necessary when using the js_ReaScriptAPI GDI functions, which always takes values in the opposite byte order.

Parameters
color (number)

the 24-bit packed numeric color value

Return Values
(number)

the color whose byte order has been inverted

rtk.color.get_reaper_theme_bg()

Gets the background color of the current REAPER theme.

This function requres either REAPER 6.11 or later, or the SWS Extension.

Return Values
(string or nil)

the HTML-style hex color string of the current theme's background in the form #rrggbbaa, or nil if the system is running a version of REAPER prior to 6.11 without the SWS extension.

rtk.color.get_icon_style(color, under)

Determines whether light or dark icons should be used given a background color.

Dark icons will be used when the ultimate luminance of the given color(s) exceeds rtk.light_luma_threshold.

Parameters
color (string or table)

the background color (format per rtk.color.set)

under (string, table or nil)

if defined, defines the color underneath, which is used if the color parameter has has an alpha channel value less than 1.

Return Values
(string)

either the literal string light or dark depending which icon style is indicated given the background color

rtk.color.hex2rgba(s)

Converts an HTML-style hex formatted color to RGBA.

It's recommended to use rtk.color.rgba() instead, which calls this function behind the scenes.

Parameters
s (string)

a color in the form #rrggbb or #rrggbbaa

Return Values
1. (number)

the red channel from 0.0 to 1.0

2. (number)

the green channel from 0.0 to 1.0

3. (number)

the blue channel from 0.0 to 1.0

4. (number)

the alpha channel from 0.0 to 1.0, where 1.0 is assumed if the given color string is in the form #rrggbb.

rtk.color.rgba2hex(r, g, b, a)

Converts an RGBA color to an HTML-style hex formatted string.

Parameters
r (number)

the red channel from 0.0 to 1.0

g (number)

the green channel from 0.0 to 1.0

b (number)

the blue channel from 0.0 to 1.0

a (number or nil)

the optional alpha channel from 0.0 to 1.0

Return Values
(string)

a color in the form #rrggbb if no alpha channel was given or if alpha is 1.0, otherwise the color will be in the form #rrggbbaa

rtk.color.int2hex(n, native)

Convert a 24-bit packed integer color to an HTML-style hex formatted color string.

If you have a packed color value with a different byte order, you can first call rtk.color.flip_byte_order().

To convert in the other direction (a hex value to a packed integer) you can use rtk.color.int().

Parameters
n (number)

a 24-bit packed integer holding red in the low byte and blue in the high byte.

native (boolean or nil)

if true, the given value will be filtered through rtk.color.convert_native() before converting to hex.

Return Values
(string)

an HTML-style hex formatted string in the form #rrggbb.

rtk.color.hsv2rgb(h, s, v, a)

Converts an HSV(A) color to RGB(A).

Parameters
h (number)

the hue channel from 0.0 to 1.0

s (number)

the saturation channel from 0.0 to 1.0

v (number)

the value (aka brightness) channel from 0.0 to 1.0

a (number or nil)

the optional alpha channel from 0.0 to 1.0

Return Values
1. (number)

the red channel from 0.0 to 1.0

2. (number)

the green channel from 0.0 to 1.0

3. (number)

the blue channel from 0.0 to 1.0

4. (number)

the alpha channel from 0.0 to 1.0, or 1.0 if a was nil

rtk.color.hsl2rgb(h, s, l, a)

Converts an HSL(A) color to RGB(A).

Parameters
h (number)

the hue channel from 0.0 to 1.0

s (number)

the saturation channel from 0.0 to 1.0

l (number)

the lightness channel from 0.0 to 1.0

a (number or nil)

the optional alpha channel from 0.0 to 1.0

Return Values
1. (number)

the red channel from 0.0 to 1.0

2. (number)

the green channel from 0.0 to 1.0

3. (number)

the blue channel from 0.0 to 1.0

4. (number)

the alpha channel from 0.0 to 1.0, or 1.0 if a was nil