package matrix
Build not yet checkedInstall
dune-project
Dependency
Authors
Maintainers
Sources
sha256=a92cbbcbe016fb19fb0a749222da0e459a9567aef3f4c7340d9bd6b71c53ed6f
sha512=6a7ab054605538bb31a2b73a1a6d093981a2704c9f0af5852221c05735290d74aca7c7282298c4d0f91e86a800e2ccd94b4918af883cd963449c758eb6b272b3
doc/matrix.ansi/Ansi/Color/index.html
Module Ansi.ColorSource
Colors.
Colors, as a terminal is told to show them.
A terminal is told a color in one of three ways, each with its own SGR codes. It is told an RGB value (38;2;r;g;b), an entry of its palette (38;5;n), or its default color (39 or 49). A color of this module records which, its intent (intent), so that SGR output names the color the program chose. It also records an RGBA value, its snapshot. The RGB of the snapshot is what this module assumes the color looks like, and its alpha weights the color when it is blended over another, by source-over compositing (blend). Blending and comparing work on snapshots, and SGR output works on intents.
The snapshot of a palette entry is the RGB the section Color depth gives it. The snapshot of the default foreground is white and that of the default background black. The colors a terminal shows for them, and for its entries, are its palette (Palette). A color whose alpha is 0 is transparent, and SGR writes a transparent RGB color as the default color.
Constructors clamp out-of-range components and do not raise, except of_hex_exn.
This blends a translucent red over the default background. The result is an RGB color, half the red's intensity over black:
let c =
Ansi.Color.blend
~src:(Ansi.Color.of_rgba 255 0 0 128)
~dst:Ansi.Color.default_bg
in
assert (Ansi.Color.to_sgr_codes ~bg:true c = [ 48; 2; 128; 0; 0 ])Colors
The type for colors.
The type for intents.
Constructors
transparent is the transparent RGB color with a black snapshot. Blending it over a color leaves that color unchanged.
Palette colors
black to white are palette entries 0 to 7, and bright_black to bright_white entries 8 to 15, as indexed gives them.
Other colors
of_rgb r g b is the opaque RGB color (r, g, b), each component clamped to [0;255].
of_rgba r g b a is the RGB color (r, g, b) with alpha a, each component clamped to [0;255].
indexed i is palette entry i, clamped to [0;255], with the snapshot Color depth gives it.
grayscale ~level is palette entry 232 + level, the gray of level level, clamped to [0;23], from darkest to lightest.
of_hsl ~h ~s ~l ?a () is the RGB color of hue h in degrees, saturation s and lightness l, with alpha a. h is taken modulo 360, and s, l and a are clamped to [0.0;1.0]. a defaults to 1.0.
of_hex s is the RGB color written in s as RGB, RGBA, RRGGBB or RRGGBBAA in hexadecimal digits, optionally after a '#', and None if s has another form. A digit of the short forms stands for two equal digits, and a form without alpha is opaque.
Predicates and comparisons
equal a b is true iff a and b have the same intent and the same snapshot.
equal_rgba a b is true iff a and b have the same snapshot, whatever their intents.
Properties
to_rgba_f c is c's snapshot with each component in [0.0;1.0].
with_rgba_f c f is f r g b a, where (r, g, b, a) is to_rgba_f c. It builds no tuple.
to_hsl c is (h, s, l, a), the hue in [0.0;360.0\), the saturation and the lightness in [0.0;1.0] of c's snapshot, and its alpha.
Operations
blend ~src ~dst is src composited over dst by source-over blending of their snapshots. It is dst if src is transparent and src if src is opaque, intents included. Otherwise it is an RGB color whose alpha combines the two.
invert c is the opaque RGB color whose components are 255 - v for each component v of the RGB of c's snapshot.
contrast a b is the contrast ratio of the RGB of a's and b's snapshots, from 1.0 for two equal colors to 21.0 for black and white. It is WCAG 2's ratio, (l1 + 0.05) / (l2 + 0.05), where l1 is the higher relative luminance of the two and l2 the lower, and it is symmetric. WCAG asks at least 4.5 of text against its background and 3.0 of a graphical object. Alpha and intent are ignored, so a palette entry or a default color is judged by the RGB this module assumes for it (Color depth). Palette.contrast judges colors as a terminal of a known palette shows them.
Color depth
A terminal shows colors at one of a few depths. With direct color it shows any RGB value (38;2). With 256 colors it shows the entries of xterm's palette (38;5). Entries 0 to 15 are the 16 colors below, 16 to 231 a 6×6×6 cube whose levels in each channel are 0, 95, 135, 175, 215 and 255, and 232 to 255 a ramp of grays from 8 to 238 by steps of 10, which leaves out black and white. With 16 colors it shows entries 0 to 15 (30..37, 90..97), with 8 colors entries 0 to 7, and a monochrome terminal shows only its default colors.
Entries 16 to 255 are the same in every terminal that has them. Entries 0 to 15 vary, since xterm takes them from its resources and users and themes set them, so a program cannot know them. indexed gives them the 16 colors of HTML 4.01 (maroon #800000, green #008000, ..., silver #c0c0c0, gray #808080, red #ff0000, ..., white #ffffff), which this module uses wherever it needs their RGB.
The type for color depths, which are direct color, 256, 16 and 8 colors, and only the default colors.
to_depth d c is c as a terminal of depth d can show it:
- A
Defaultcolor is unchanged at every depth, and so is every color at`Truecolor. - At
`Monoevery color becomes the default color withc's snapshot. - At
`Ansi256,`Ansi16and`Ansi8, a color alreadyIndexedwithin the depth, or with alpha0, is unchanged. Any other color becomes the palette entry nearest to the RGB of its snapshot, one of 16 to 255 at`Ansi256, one of 0 to 15 at`Ansi16and one of 0 to 7 at`Ansi8. It keepsc's alpha.
Nearest is by the squared Euclidean distance between RGB values, a tie going to the higher entry. xterm shows a direct color this way when it is built without direct-color support: "it uses the closest match in its palette for the given RGB" (ctlseqs, SGR 38). At `Ansi256 the search leaves out entries 0 to 15, whose colors the user sets, so the result shows the color it was chosen for. At `Ansi16 and `Ansi8 those are the only entries, and the result is nearest by the colors indexed assumes.
to_depth reads no environment. The caller gives the depth, from what the terminal reports.
SGR codes
to_sgr_codes ~depth ~bg c is the SGR codes of to_depth depth c's intent (intent), for the foreground, or for the background if bg is true. At `Ansi16 and `Ansi8 a palette entry i is written as 30 + i when i < 8 and as 82 + i otherwise, or 40 + i and 92 + i for the background, and at the other depths as 38;5;i or 48;5;i. depth defaults to `Truecolor.
emit_sgr_codes ~depth ~bg push c calls push on each code of to_sgr_codes ~depth ~bg c, in order, and builds no list.
Packed colors
Colors as immediate integers, for code that stores many colors, such as the planes of a grid.
Converting
to_hex c is "#rrggbb", the RGB of c's snapshot in lowercase hexadecimal digits.
Formatting
pp ppf c formats c for inspection, such as Red, Indexed(42), Rgb(1,2,3), Rgba(1,2,3,4) or Default.