color
¶
Except where indicated, functions and attributes across rtk that take a color value can be specified in one of the following formats:
'name': the case-insensitive name of a
CSS color keyword
where alpha is assumed to be 1.0'name#aa': the case-insensitive name of a
CSS color keyword
where alpha specified as a two hexdigit code delimited by a hash'#rrggbb' : HTML hex style string where alpha is assumed to be 1.0'#rrggbbaa': HTML hex style string with alpha{r, g, b}: 3-element table holding red, green, and blue numeric values
between 0 and 1.0{r, g, b, a}: 4-element table, as above plus alpha between 0 and 1.0While 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.
-- 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})
| rtk.color.names¶ | table | read/write |
A table that maps CSS color names to
HTML-style hex color strings. All color names are lowercase, without spaces or special
characters. A special You can also insert your own custom color names into this table: |
| rtk.color.set() | Sets the graphic context to the given color before drawing to a surface
set by |
| 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) |
Sets the graphic context to the given color before drawing to a surface
set by rtk.pushdest().
| 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 |
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.
| color | (colortype) | the color value to parse |
| 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. |
Returns the relative luminance of the given color.
| 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 |
| (number) | the relative luminance from 0.0 to 1.0 |
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.
| color | (colortype) | the color to convert to HSV |
| 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 |
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.
| color | (colortype) | the color to convert to HSL |
| 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 |
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.
-- 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
| color | (colortype) | the color to modify |
| native | (boolean or nil) | if true, the returned value will be filtered through |
| (number) | a 24-bit packed integer with red in the low byte and blue in the high byte |
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().
| 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) |
| 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 |
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.
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.
| n | (number) | the numeric color that is either REAPER- or OS-native |
| (number) | the converted 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.
| color | (number) | the 24-bit packed numeric color value |
| (number) | the color whose byte order has been inverted |
Gets the background color of the current REAPER theme.
This function requres either REAPER 6.11 or later, or the SWS Extension.
| (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. |
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.
| color | (string or table) | the background color (format per |
| under | (string, table or nil) | if defined, defines the color underneath, which is used if the |
| (string) | either the literal string |
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.
| s | (string) | a color in the form |
| 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 |
Converts an RGBA color to an HTML-style hex formatted string.
| 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 |
| (string) | a color in the form |
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().
| 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 |
| (string) | an HTML-style hex formatted string in the form |
Converts an HSV(A) color to RGB(A).
| 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 |
| 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 |
Converts an HSL(A) color to RGB(A).
| 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 |
| 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 |