Color parsing, palette generation, color math, and X11 color name utilities shared by libghostty-vt.
These APIs expose Ghostty's color semantics directly to embedders. Use them when an application needs to parse the same color strings as Ghostty config and theme files, generate the same 256-color palette used by the terminal, list supported X11 color names, or make UI decisions from luminance and contrast values.
Parsing Colors
ghostty_color_parse() accepts the flexible syntax used by Ghostty for terminal colors:
- X11 color names, matched ASCII case-insensitively.
- 3- or 6-digit hex colors, with or without a leading #.
- 9- or 12-digit hex colors, with a leading #.
- XParseColor-style rgb:<red>/<green>/<blue> values.
- XParseColor-style rgbi:<red>/<green>/<blue> values.
Leading and trailing spaces and tabs are ignored. Use ghostty_color_parse_x11() when only X11 names should be accepted.
"ForestGreen",
sizeof("ForestGreen") - 1,
}
GHOSTTY_API GhosttyResult ghostty_color_parse(const char *value, size_t len, GhosttyColorRgb *out)
Palette Entries
ghostty_color_parse_palette_entry() parses a single Ghostty palette override in INDEX=COLOR form. The index may be decimal or use a 0x, 0o, or 0b prefix. The color side uses ghostty_color_parse().
uint8_t index;
"0x10=#282c34",
sizeof("0x10=#282c34") - 1,
&index,
palette[index] = rgb;
}
GHOSTTY_API GhosttyResult ghostty_color_parse_palette_entry(const char *value, size_t len, uint8_t *out_index, GhosttyColorRgb *out_rgb)
GHOSTTY_API void ghostty_color_palette_default(GhosttyColorRgb *out)
Palette Generation
ghostty_color_palette_generate() derives the 216-color cube and grayscale ramp from a base palette, background, and foreground. Set bits in GhosttyColorPaletteMask preserve specific indices from the base palette. The output may alias the base input.
palette,
&skip,
background,
foreground,
true,
palette);
GHOSTTY_API void ghostty_color_palette_generate(const GhosttyColorRgb *base, const GhosttyColorPaletteMask *skip, GhosttyColorRgb bg, GhosttyColorRgb fg, bool harmonious, GhosttyColorRgb *out)
#define GHOSTTY_COLOR_PALETTE_MASK_SET(mask, index)
X11 Color Names
The X11 name table is static program-lifetime memory. Entries are in rgb.txt order and are terminated by an entry with name == NULL. ghostty_color_x11_name_count() returns the number of non-terminator entries.
for (size_t i = 0; i < count; i++) {
}
GHOSTTY_API size_t ghostty_color_x11_name_count(void)
GHOSTTY_API const GhosttyColorX11Entry * ghostty_color_x11_names(void)
|
| GHOSTTY_API void | ghostty_color_rgb_get (GhosttyColorRgb color, uint8_t *r, uint8_t *g, uint8_t *b) |
| GHOSTTY_API GhosttyResult | ghostty_color_parse_x11 (const char *name, size_t len, GhosttyColorRgb *out) |
| GHOSTTY_API GhosttyResult | ghostty_color_parse (const char *value, size_t len, GhosttyColorRgb *out) |
| GHOSTTY_API GhosttyResult | ghostty_color_parse_palette_entry (const char *value, size_t len, uint8_t *out_index, GhosttyColorRgb *out_rgb) |
| GHOSTTY_API void | ghostty_color_palette_default (GhosttyColorRgb *out) |
| GHOSTTY_API void | ghostty_color_palette_generate (const GhosttyColorRgb *base, const GhosttyColorPaletteMask *skip, GhosttyColorRgb bg, GhosttyColorRgb fg, bool harmonious, GhosttyColorRgb *out) |
| GHOSTTY_API double | ghostty_color_luminance (GhosttyColorRgb color) |
| GHOSTTY_API double | ghostty_color_perceived_luminance (GhosttyColorRgb color) |
| GHOSTTY_API double | ghostty_color_contrast (GhosttyColorRgb a, GhosttyColorRgb b) |
| GHOSTTY_API const GhosttyColorX11Entry * | ghostty_color_x11_names (void) |
| GHOSTTY_API size_t | ghostty_color_x11_name_count (void) |
Generate a 256-color palette from base colors.
The base palette supplies indices 0-15, which are always preserved. If base is NULL, Ghostty's default palette is used. If skip is NULL, no extra indices are skipped. Set bits in skip preserve those indices from base. The 216-color cube at indices 16-231 is generated with trilinear CIELAB interpolation, and the grayscale ramp at indices 232-255 is interpolated from the background to the foreground.
For light themes, harmonious controls whether the generated palette keeps the background-to-foreground orientation. When false, Ghostty swaps the light background and dark foreground so the cube and ramp run dark-to-light. The output palette may be the same pointer as base.
- Parameters
-
| base | The base palette, an array of exactly 256 GhosttyColorRgb values, or NULL to use Ghostty's default palette |
| skip | The palette indices to preserve from base, or NULL for an empty mask |
| bg | The terminal background color |
| fg | The terminal foreground color |
| harmonious | Whether light themes keep background-to-foreground orientation |
| [out] | out | The output palette, an array of exactly 256 GhosttyColorRgb values |
1.16.1