Colors

Parse colors, generate palettes, and look up X11 color names. More...

Detailed Description

Parse colors, generate palettes, and look up X11 color names.

These are Ghostty's own color rules, so you don't have to write them again: the color strings its config and theme files accept, the 256-color palette the terminal uses, and the X11 color names.

Use them when your application has to agree with Ghostty about what a color means, or to make UI decisions from luminance and contrast values. You don't need a terminal.

Example

GhosttyColorRgb color;
ghostty_color_parse("#abc", sizeof("#abc") - 1, &color);

See the Colors guide for parsing, palettes, and how a terminal's colors work. c-vt-colors sets a terminal's colors with these types.

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 59 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

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

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

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

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

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

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

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

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)

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

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

Macro Definition Documentation

GHOSTTY_COLOR_NAMED_BLACK

#define GHOSTTY_COLOR_NAMED_BLACK   0

Black color (0)

Examples

c-vt-colors/src/main.c.

Definition at line 147 of file color.h.

GHOSTTY_COLOR_NAMED_BLUE

#define GHOSTTY_COLOR_NAMED_BLUE   4

Blue color (4)

Examples

c-vt-colors/src/main.c.

Definition at line 155 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_BLACK

#define GHOSTTY_COLOR_NAMED_BRIGHT_BLACK   8

Bright black color (8)

Definition at line 163 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_BLUE

#define GHOSTTY_COLOR_NAMED_BRIGHT_BLUE   12

Bright blue color (12)

Definition at line 171 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_CYAN

#define GHOSTTY_COLOR_NAMED_BRIGHT_CYAN   14

Bright cyan color (14)

Definition at line 175 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_GREEN

#define GHOSTTY_COLOR_NAMED_BRIGHT_GREEN   10

Bright green color (10)

Definition at line 167 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA

#define GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA   13

Bright magenta color (13)

Definition at line 173 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_RED

#define GHOSTTY_COLOR_NAMED_BRIGHT_RED   9

Bright red color (9)

Definition at line 165 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_WHITE

#define GHOSTTY_COLOR_NAMED_BRIGHT_WHITE   15

Bright white color (15)

Definition at line 177 of file color.h.

GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW

#define GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW   11

Bright yellow color (11)

Definition at line 169 of file color.h.

GHOSTTY_COLOR_NAMED_CYAN

#define GHOSTTY_COLOR_NAMED_CYAN   6

Cyan color (6)

Examples

c-vt-colors/src/main.c.

Definition at line 159 of file color.h.

GHOSTTY_COLOR_NAMED_GREEN

#define GHOSTTY_COLOR_NAMED_GREEN   2

Green color (2)

Examples

c-vt-colors/src/main.c.

Definition at line 151 of file color.h.

GHOSTTY_COLOR_NAMED_MAGENTA

#define GHOSTTY_COLOR_NAMED_MAGENTA   5

Magenta color (5)

Examples

c-vt-colors/src/main.c.

Definition at line 157 of file color.h.

GHOSTTY_COLOR_NAMED_RED

#define GHOSTTY_COLOR_NAMED_RED   1

Red color (1)

Examples

c-vt-colors/src/main.c.

Definition at line 149 of file color.h.

GHOSTTY_COLOR_NAMED_WHITE

#define GHOSTTY_COLOR_NAMED_WHITE   7

White color (7)

Examples

c-vt-colors/src/main.c.

Definition at line 161 of file color.h.

GHOSTTY_COLOR_NAMED_YELLOW

#define GHOSTTY_COLOR_NAMED_YELLOW   3

Yellow color (3)

Examples

c-vt-colors/src/main.c.

Definition at line 153 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 110 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 143 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 120 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 131 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 101 of file color.h.