-- SPDX-FileCopyrightText: 2017 Daniel Ratcliffe -- -- SPDX-License-Identifier: LicenseRef-CCPL --[[- Constants and functions for colour values, suitable for working with [`term`] and [`redstone`]. This is useful in conjunction with [Bundled Cables][`redstone.setBundledOutput`] from mods like Project Red, and [colors on Advanced Computers and Advanced Monitors][`term.setTextColour`]. For the non-American English version just replace [`colors`] with [`colours`]. This alternative API is exactly the same, except the colours use British English (e.g. [`colors.gray`] is spelt [`colours.grey`]). On basic terminals (such as the Computer and Monitor), all the colors are converted to grayscale. This means you can still use all 16 colors on the screen, but they will appear as the nearest tint of gray. You can check if a terminal supports color by using the function [`term.isColor`]. Grayscale colors are calculated by taking the average of the three components, i.e. `(red + green + blue) / 3`.
Default Colors
Color Value Default Palette Color
DecHexPaint/Blit PreviewHexRGBGrayscale
colors.white 10x10 #F0F0F0240, 240, 240
colors.orange 20x21 #F2B233242, 178, 51
colors.magenta 40x42 #E57FD8229, 127, 216
colors.lightBlue 80x83 #99B2F2153, 178, 242
colors.yellow 160x104 #DEDE6C222, 222, 108
colors.lime 320x205 #7FCC19127, 204, 25
colors.pink 640x406 #F2B2CC242, 178, 204
colors.gray 1280x807 #4C4C4C76, 76, 76
colors.lightGray 2560x1008 #999999153, 153, 153
colors.cyan 5120x2009 #4C99B276, 153, 178
colors.purple 10240x400a #B266E5178, 102, 229
colors.blue 20480x800b #3366CC51, 102, 204
colors.brown 40960x1000c #7F664C127, 102, 76
colors.green 81920x2000d #57A64E87, 166, 78
colors.red 163840x4000e #CC4C4C204, 76, 76
colors.black 327680x8000f #11111117, 17, 17
@see colours @module colors ]] local expect = dofile("rom/modules/main/cc/expect.lua").expect --- White: Written as `0` in paint files and [`term.blit`], has a default -- terminal colour of #F0F0F0. white = 0x1 --- Orange: Written as `1` in paint files and [`term.blit`], has a -- default terminal colour of #F2B233. orange = 0x2 --- Magenta: Written as `2` in paint files and [`term.blit`], has a -- default terminal colour of #E57FD8. magenta = 0x4 --- Light blue: Written as `3` in paint files and [`term.blit`], has a -- default terminal colour of #99B2F2. lightBlue = 0x8 --- Yellow: Written as `4` in paint files and [`term.blit`], has a -- default terminal colour of #DEDE6C. yellow = 0x10 --- Lime: Written as `5` in paint files and [`term.blit`], has a default -- terminal colour of #7FCC19. lime = 0x20 --- Pink: Written as `6` in paint files and [`term.blit`], has a default -- terminal colour of #F2B2CC. pink = 0x40 --- Gray: Written as `7` in paint files and [`term.blit`], has a default -- terminal colour of #4C4C4C. gray = 0x80 --- Light gray: Written as `8` in paint files and [`term.blit`], has a -- default terminal colour of #999999. lightGray = 0x100 --- Cyan: Written as `9` in paint files and [`term.blit`], has a default -- terminal colour of #4C99B2. cyan = 0x200 --- Purple: Written as `a` in paint files and [`term.blit`], has a -- default terminal colour of #B266E5. purple = 0x400 --- Blue: Written as `b` in paint files and [`term.blit`], has a default -- terminal colour of #3366CC. blue = 0x800 --- Brown: Written as `c` in paint files and [`term.blit`], has a default -- terminal colour of #7F664C. brown = 0x1000 --- Green: Written as `d` in paint files and [`term.blit`], has a default -- terminal colour of #57A64E. green = 0x2000 --- Red: Written as `e` in paint files and [`term.blit`], has a default -- terminal colour of #CC4C4C. red = 0x4000 --- Black: Written as `f` in paint files and [`term.blit`], has a default -- terminal colour of #111111. black = 0x8000 --- Combines a set of colors (or sets of colors) into a larger set. Useful for -- Bundled Cables. -- -- @tparam number ... The colors to combine. -- @treturn number The union of the color sets given in `...` -- @since 1.2 -- @usage -- ```lua -- colors.combine(colors.white, colors.magenta, colours.lightBlue) -- -- => 13 -- ``` function combine(...) local r = 0 for i = 1, select('#', ...) do local c = select(i, ...) expect(i, c, "number") r = bit32.bor(r, c) end return r end --- Removes one or more colors (or sets of colors) from an initial set. Useful -- for Bundled Cables. -- -- Each parameter beyond the first may be a single color or may be a set of -- colors (in the latter case, all colors in the set are removed from the -- original set). -- -- @tparam number colors The color from which to subtract. -- @tparam number ... The colors to subtract. -- @treturn number The resulting color. -- @since 1.2 -- @usage -- ```lua -- colours.subtract(colours.lime, colours.orange, colours.white) -- -- => 32 -- ``` function subtract(colors, ...) expect(1, colors, "number") local r = colors for i = 1, select('#', ...) do local c = select(i, ...) expect(i + 1, c, "number") r = bit32.band(r, bit32.bnot(c)) end return r end --- Tests whether `color` is contained within `colors`. Useful for Bundled -- Cables. -- -- @tparam number colors A color, or color set -- @tparam number color A color or set of colors that `colors` should contain. -- @treturn boolean If `colors` contains all colors within `color`. -- @since 1.2 -- @usage -- ```lua -- colors.test(colors.combine(colors.white, colors.magenta, colours.lightBlue), colors.lightBlue) -- -- => true -- ``` function test(colors, color) expect(1, colors, "number") expect(2, color, "number") return bit32.band(colors, color) == color end --- Combine a three-colour RGB value into one hexadecimal representation. -- -- @tparam number r The red channel, should be between 0 and 1. -- @tparam number g The green channel, should be between 0 and 1. -- @tparam number b The blue channel, should be between 0 and 1. -- @treturn number The combined hexadecimal colour. -- @usage -- ```lua -- colors.packRGB(0.7, 0.2, 0.6) -- -- => 0xb23399 -- ``` -- @since 1.81.0 function packRGB(r, g, b) expect(1, r, "number") expect(2, g, "number") expect(3, b, "number") return bit32.band(r * 255, 0xFF) * 2 ^ 16 + bit32.band(g * 255, 0xFF) * 2 ^ 8 + bit32.band(b * 255, 0xFF) end --- Separate a hexadecimal RGB colour into its three constituent channels. -- -- @tparam number rgb The combined hexadecimal colour. -- @treturn number The red channel, will be between 0 and 1. -- @treturn number The green channel, will be between 0 and 1. -- @treturn number The blue channel, will be between 0 and 1. -- @usage -- ```lua -- colors.unpackRGB(0xb23399) -- -- => 0.7, 0.2, 0.6 -- ``` -- @see colors.packRGB -- @since 1.81.0 function unpackRGB(rgb) expect(1, rgb, "number") return bit32.band(bit32.rshift(rgb, 16), 0xFF) / 255, bit32.band(bit32.rshift(rgb, 8), 0xFF) / 255, bit32.band(rgb, 0xFF) / 255 end --- Either calls [`colors.packRGB`] or [`colors.unpackRGB`], depending on how many -- arguments it receives. -- -- @tparam[1] number r The red channel, as an argument to [`colors.packRGB`]. -- @tparam[1] number g The green channel, as an argument to [`colors.packRGB`]. -- @tparam[1] number b The blue channel, as an argument to [`colors.packRGB`]. -- @tparam[2] number rgb The combined hexadecimal color, as an argument to [`colors.unpackRGB`]. -- @treturn[1] number The combined hexadecimal colour, as returned by [`colors.packRGB`]. -- @treturn[2] number The red channel, as returned by [`colors.unpackRGB`] -- @treturn[2] number The green channel, as returned by [`colors.unpackRGB`] -- @treturn[2] number The blue channel, as returned by [`colors.unpackRGB`] -- @deprecated Use [`packRGB`] or [`unpackRGB`] directly. -- @usage -- ```lua -- colors.rgb8(0xb23399) -- -- => 0.7, 0.2, 0.6 -- ``` -- @usage -- ```lua -- colors.rgb8(0.7, 0.2, 0.6) -- -- => 0xb23399 -- ``` -- @since 1.80pr1 -- @changed 1.81.0 Deprecated in favor of colors.(un)packRGB. function rgb8(r, g, b) if g == nil and b == nil then return unpackRGB(r) else return packRGB(r, g, b) end end -- Colour to hex lookup table for toBlit local color_hex_lookup = {} for i = 0, 15 do color_hex_lookup[2 ^ i] = string.format("%x", i) end --[[- Converts the given color to a paint/blit hex character (0-9a-f). This is equivalent to converting floor(log_2(color)) to hexadecimal. @tparam number color The color to convert. @treturn string The blit hex code of the color. @usage ```lua colors.toBlit(colors.red) -- => "c" ``` @see colors.fromBlit @since 1.94.0 ]] function toBlit(color) expect(1, color, "number") return color_hex_lookup[color] or string.format("%x", math.floor(math.log(color, 2))) end --[[- Converts the given paint/blit hex character (0-9a-f) to a color. This is equivalent to converting the hex character to a number and then 2 ^ decimal @tparam string hex The paint/blit hex character to convert @treturn number The color @usage ```lua colors.fromBlit("e") -- => 16384 ``` @see colors.toBlit @since 1.105.0 ]] function fromBlit(hex) expect(1, hex, "string") if #hex ~= 1 then return nil end local value = tonumber(hex, 16) if not value then return nil end return 2 ^ value end