Color Utilities

Detailed Description

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.

GhosttyColorRgb color;
 
if (ghostty_color_parse(
        "ForestGreen",
        sizeof("ForestGreen") - 1,
        &color) != GHOSTTY_SUCCESS) {
  // Handle invalid color input.
}
 
ghostty_color_parse("#abc", sizeof("#abc") - 1, &color);
ghostty_color_parse("rgb:12/34/56", sizeof("rgb:12/34/56") - 1, &color);

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().

GhosttyColorRgb palette[256];
ghostty_color_palette_default(palette);
 
uint8_t index;
GhosttyColorRgb rgb;
 
if (ghostty_color_parse_palette_entry(
        "0x10=#282c34",
        sizeof("0x10=#282c34") - 1,
        &index,
        &rgb) == GHOSTTY_SUCCESS) {
  palette[index] = rgb;
}

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.

GhosttyColorRgb palette[256];
ghostty_color_palette_default(palette);
 
GhosttyColorPaletteMask skip = {0};
GHOSTTY_COLOR_PALETTE_MASK_SET(&skip, 16);
 
GhosttyColorRgb background = {40, 44, 52};
GhosttyColorRgb foreground = {220, 223, 228};
 
ghostty_color_palette_generate(
    palette,
    &skip,
    &background,
    &foreground,
    true,
    palette);

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.

const GhosttyColorX11Entry* names = ghostty_color_x11_names();
size_t count = ghostty_color_x11_name_count();
 
for (size_t i = 0; i < count; i++) {
  // names[i].name and names[i].color are valid here.
}

Typedefs
typedef uint8_t	GhosttyColorPaletteIndex

Functions
GHOSTTY_API void	ghostty_color_rgb_get (const 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, const GhosttyColorRgb *bg, const GhosttyColorRgb *fg, bool harmonious, GhosttyColorRgb *out)
GHOSTTY_API double	ghostty_color_luminance (const GhosttyColorRgb *color)
GHOSTTY_API double	ghostty_color_perceived_luminance (const GhosttyColorRgb *color)
GHOSTTY_API double	ghostty_color_contrast (const GhosttyColorRgb *a, const GhosttyColorRgb *b)
GHOSTTY_API const GhosttyColorX11Entry *	ghostty_color_x11_names (void)
GHOSTTY_API size_t	ghostty_color_x11_name_count (void)

Macros
#define	GHOSTTY_COLOR_PALETTE_MASK_WORD(index)
#define	GHOSTTY_COLOR_PALETTE_MASK_BIT(index)
#define	GHOSTTY_COLOR_PALETTE_MASK_SET(mask, index)
#define	GHOSTTY_COLOR_PALETTE_MASK_UNSET(mask, index)
#define	GHOSTTY_COLOR_PALETTE_MASK_IS_SET(mask, index)
#define	GHOSTTY_COLOR_NAMED_BLACK   0
#define	GHOSTTY_COLOR_NAMED_RED   1
#define	GHOSTTY_COLOR_NAMED_GREEN   2
#define	GHOSTTY_COLOR_NAMED_YELLOW   3
#define	GHOSTTY_COLOR_NAMED_BLUE   4
#define	GHOSTTY_COLOR_NAMED_MAGENTA   5
#define	GHOSTTY_COLOR_NAMED_CYAN   6
#define	GHOSTTY_COLOR_NAMED_WHITE   7
#define	GHOSTTY_COLOR_NAMED_BRIGHT_BLACK   8
#define	GHOSTTY_COLOR_NAMED_BRIGHT_RED   9
#define	GHOSTTY_COLOR_NAMED_BRIGHT_GREEN   10
#define	GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW   11
#define	GHOSTTY_COLOR_NAMED_BRIGHT_BLUE   12
#define	GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA   13
#define	GHOSTTY_COLOR_NAMED_BRIGHT_CYAN   14
#define	GHOSTTY_COLOR_NAMED_BRIGHT_WHITE   15

Data Structures
struct	GhosttyColorRgb
struct	GhosttyColorPaletteMask
struct	GhosttyColorX11Entry

Typedef Documentation

GhosttyColorPaletteIndex

typedef uint8_t GhosttyColorPaletteIndex

Palette color index (0-255).

Definition at line 141 of file color.h.

Function Documentation

ghostty_color_contrast()

GHOSTTY_API double ghostty_color_contrast	(	const GhosttyColorRgb *	a,
		const GhosttyColorRgb *	b )

Calculate the WCAG contrast ratio between two RGB colors.

The contrast ratio is symmetric and ranges from 1.0 for identical colors to 21.0 for black and white.

Parameters

a	The first RGB color (must not be NULL)
b	The second RGB color (must not be NULL)

Returns

WCAG contrast ratio in the range 1.0 to 21.0

References ghostty_color_contrast().

Referenced by ghostty_color_contrast().

ghostty_color_luminance()

GHOSTTY_API double ghostty_color_luminance

(

const GhosttyColorRgb *

color

)

Calculate W3C relative luminance for an RGB color.

Returns a normalized value from 0.0 for black to 1.0 for white. See https://www.w3.org/TR/WCAG20/#relativeluminancedef.

Parameters

color

The RGB color (must not be NULL)

Returns

Relative luminance in the range 0.0 to 1.0

References ghostty_color_luminance().

Referenced by ghostty_color_luminance().

ghostty_color_palette_default()

GHOSTTY_API void ghostty_color_palette_default

(

GhosttyColorRgb *

out

)

Get Ghostty's built-in default 256-color palette.

Writes exactly 256 entries: Ghostty's base16 defaults, the xterm 6x6x6 color cube, and the grayscale ramp.

Parameters

[out]

out

The output palette, an array of exactly 256 GhosttyColorRgb values

References ghostty_color_palette_default().

Referenced by ghostty_color_palette_default().

ghostty_color_palette_generate()

GHOSTTY_API void ghostty_color_palette_generate	(	const GhosttyColorRgb *	base,
		const GhosttyColorPaletteMask *	skip,
		const GhosttyColorRgb *	bg,
		const GhosttyColorRgb *	fg,
		bool	harmonious,
		GhosttyColorRgb *	out )

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 (must not be NULL)
	fg	The terminal foreground color (must not be NULL)
	harmonious	Whether light themes keep background-to-foreground orientation
[out]	out	The output palette, an array of exactly 256 GhosttyColorRgb values

References ghostty_color_palette_generate().

Referenced by ghostty_color_palette_generate().

ghostty_color_parse()

GHOSTTY_API GhosttyResult ghostty_color_parse	(	const char *	value,
		size_t	len,
		GhosttyColorRgb *	out )

Parse a flexible Ghostty color value.

Accepts Ghostty's terminal color syntax: X11 color names, hex colors in 3-, 6-, 9-, or 12-digit form (the leading # is optional for 3- and 6-digit values), and rgb:<red>/<green>/<blue> or rgbi:<red>/<green>/<blue> specifications. Leading and trailing spaces and tabs are trimmed.

Parameters

	value	The color value bytes (must not be NULL)
	len	The length of value in bytes
[out]	out	The parsed RGB color

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if parsing fails or value is NULL

References ghostty_color_parse().

Referenced by ghostty_color_parse().

ghostty_color_parse_palette_entry()

GHOSTTY_API GhosttyResult ghostty_color_parse_palette_entry	(	const char *	value,
		size_t	len,
		uint8_t *	out_index,
		GhosttyColorRgb *	out_rgb )

Parse a Ghostty palette entry.

Accepts Ghostty palette config syntax: N=COLOR. N is a palette index from 0 to 255 in decimal or in 0x, 0o, or 0b-prefixed form. Spaces and tabs around N and COLOR are ignored. COLOR accepts the same syntax as ghostty_color_parse().

Parameters

	value	The palette entry bytes (must not be NULL)
	len	The length of value in bytes
[out]	out_index	The parsed palette index
[out]	out_rgb	The parsed RGB color

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE on any failure, including index overflow

References ghostty_color_parse_palette_entry().

Referenced by ghostty_color_parse_palette_entry().

ghostty_color_parse_x11()

GHOSTTY_API GhosttyResult ghostty_color_parse_x11	(	const char *	name,
		size_t	len,
		GhosttyColorRgb *	out )

Parse an X11 color name.

The color name is resolved from Ghostty's embedded rgb.txt table. Leading and trailing spaces and tabs are trimmed, and matching is ASCII case-insensitive. Hex values are not accepted by this function.

Parameters

	name	The color name bytes (must not be NULL)
	len	The length of name in bytes
[out]	out	The parsed RGB color

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if no color matches or name is NULL

References ghostty_color_parse_x11().

Referenced by ghostty_color_parse_x11().

ghostty_color_perceived_luminance()

GHOSTTY_API double ghostty_color_perceived_luminance

(

const GhosttyColorRgb *

color

)

Calculate perceived luminance for an RGB color.

Returns a normalized value from 0.0 for black to 1.0 for white. Ghostty treats a background color as light when this exceeds 0.5. This is not the metric used internally by ghostty_color_palette_generate(), which uses CIELAB lightness.

Parameters

color

The RGB color (must not be NULL)

Returns

Perceived luminance in the range 0.0 to 1.0

References ghostty_color_perceived_luminance().

Referenced by ghostty_color_perceived_luminance().

ghostty_color_rgb_get()

GHOSTTY_API void ghostty_color_rgb_get	(	const GhosttyColorRgb *	color,
		uint8_t *	r,
		uint8_t *	g,
		uint8_t *	b )

Get the RGB color components.

This function extracts the individual red, green, and blue components from a GhosttyColorRgb value. Primarily useful in WebAssembly environments where accessing struct fields directly is difficult.

Parameters

color	Pointer to the RGB color value
r	Pointer to store the red component (0-255)
g	Pointer to store the green component (0-255)
b	Pointer to store the blue component (0-255)

References ghostty_color_rgb_get().

Referenced by ghostty_color_rgb_get().

ghostty_color_x11_name_count()

GHOSTTY_API size_t ghostty_color_x11_name_count

(

void

)

Get the number of X11 color name entries.

The returned count excludes the NULL terminator and is provided so bindings can preallocate storage before reading ghostty_color_x11_names().

Returns

Number of X11 color name entries

References ghostty_color_x11_name_count().

Referenced by ghostty_color_x11_name_count().

ghostty_color_x11_names()

GHOSTTY_API const GhosttyColorX11Entry * ghostty_color_x11_names

(

void

)

Get Ghostty's X11 color name table.

The returned pointer references static memory valid for the program lifetime and is never NULL. Entries are in rgb.txt order and are terminated by an entry with name == NULL. Aliases are separate entries, such as "medium spring green" and "MediumSpringGreen". Names are the exact supported spellings from rgb.txt; ghostty_color_parse_x11() also matches them case-insensitively.

for (const GhosttyColorX11Entry* e = ghostty_color_x11_names();
     e->name != NULL;
     e++) {
  // e->name and e->color are valid here.
}

Returns

Pointer to the first X11 color entry

References ghostty_color_x11_names().

Referenced by ghostty_color_x11_names().

Macro Definition Documentation

GHOSTTY_COLOR_NAMED_BLACK

#define GHOSTTY_COLOR_NAMED_BLACK   0

Black color (0)

Definition at line 229 of file color.h.

GHOSTTY_COLOR_NAMED_BLUE

#define GHOSTTY_COLOR_NAMED_BLUE   4

Blue color (4)

Definition at line 237 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_BLACK

#define GHOSTTY_COLOR_NAMED_BRIGHT_BLACK   8

Bright black color (8)

Definition at line 245 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_BLUE

#define GHOSTTY_COLOR_NAMED_BRIGHT_BLUE   12

Bright blue color (12)

Definition at line 253 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_CYAN

#define GHOSTTY_COLOR_NAMED_BRIGHT_CYAN   14

Bright cyan color (14)

Definition at line 257 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_GREEN

#define GHOSTTY_COLOR_NAMED_BRIGHT_GREEN   10

Bright green color (10)

Definition at line 249 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA

#define GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA   13

Bright magenta color (13)

Definition at line 255 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_RED

#define GHOSTTY_COLOR_NAMED_BRIGHT_RED   9

Bright red color (9)

Definition at line 247 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_WHITE

#define GHOSTTY_COLOR_NAMED_BRIGHT_WHITE   15

Bright white color (15)

Definition at line 259 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW

#define GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW   11

Bright yellow color (11)

Definition at line 251 of file color.h.

GHOSTTY_COLOR_NAMED_CYAN

#define GHOSTTY_COLOR_NAMED_CYAN   6

Cyan color (6)

Definition at line 241 of file color.h.

GHOSTTY_COLOR_NAMED_GREEN

#define GHOSTTY_COLOR_NAMED_GREEN   2

Green color (2)

Definition at line 233 of file color.h.

GHOSTTY_COLOR_NAMED_MAGENTA

#define GHOSTTY_COLOR_NAMED_MAGENTA   5

Magenta color (5)

Definition at line 239 of file color.h.

GHOSTTY_COLOR_NAMED_RED

#define GHOSTTY_COLOR_NAMED_RED   1

Red color (1)

Definition at line 231 of file color.h.

GHOSTTY_COLOR_NAMED_WHITE

#define GHOSTTY_COLOR_NAMED_WHITE   7

White color (7)

Definition at line 243 of file color.h.

GHOSTTY_COLOR_NAMED_YELLOW

#define GHOSTTY_COLOR_NAMED_YELLOW   3

Yellow color (3)

Definition at line 235 of file color.h.

GHOSTTY_COLOR_PALETTE_MASK_BIT

#define GHOSTTY_COLOR_PALETTE_MASK_BIT

(

index

)

Value:

(UINT64_C(1) << ((index) & 63))

Return the storage bit for a palette mask index.

Parameters

index

The palette index (0-255)

Definition at line 192 of file color.h.

GHOSTTY_COLOR_PALETTE_MASK_IS_SET

#define GHOSTTY_COLOR_PALETTE_MASK_IS_SET	(		mask,
			index )

Value:

(((mask)->bits[GHOSTTY_COLOR_PALETTE_MASK_WORD(index)] & GHOSTTY_COLOR_PALETTE_MASK_BIT(index)) != 0)

Test whether a palette mask index is set.

Parameters

mask	Pointer to a GhosttyColorPaletteMask
index	The palette index (0-255)

Returns

true if the palette index is set, false otherwise

Definition at line 225 of file color.h.

GHOSTTY_COLOR_PALETTE_MASK_SET

#define GHOSTTY_COLOR_PALETTE_MASK_SET	(		mask,
			index )

Value:

((mask)->bits[GHOSTTY_COLOR_PALETTE_MASK_WORD(index)] |= GHOSTTY_COLOR_PALETTE_MASK_BIT(index))

Set a palette mask index.

Parameters

mask	Pointer to a GhosttyColorPaletteMask
index	The palette index (0-255)

Definition at line 202 of file color.h.

GHOSTTY_COLOR_PALETTE_MASK_UNSET

#define GHOSTTY_COLOR_PALETTE_MASK_UNSET	(		mask,
			index )

Value:

((mask)->bits[GHOSTTY_COLOR_PALETTE_MASK_WORD(index)] &= ~GHOSTTY_COLOR_PALETTE_MASK_BIT(index))

Clear a palette mask index.

Parameters

mask	Pointer to a GhosttyColorPaletteMask
index	The palette index (0-255)

Definition at line 213 of file color.h.

GHOSTTY_COLOR_PALETTE_MASK_WORD

#define GHOSTTY_COLOR_PALETTE_MASK_WORD

(

index

)

Value:

((index) >> 6)

Return the storage word for a palette mask index.

Parameters

index

The palette index (0-255)

Definition at line 183 of file color.h.