LWXGL Color Palette: 16-Color System and Runtime Editing

All color parameters in LWXGL are integer indices into a fixed, 16-entry RGB palette. Rather than accepting arbitrary hex values, every API that takes a color argument expects a number from 0 to 15. The palette is allocated as X11 color cells when GCreateWindow is called and can be read or modified at runtime through the GPalette* family of functions.

Default Palette

The following 16 colors are loaded automatically at startup. They cover a classic CGA/terminal-inspired range from black through to white, including dark and light variants of the primary and secondary colors.

Index	Name	R	G	B
0	Black	0	0	0
1	Dark Blue	3	3	173
2	Dark Green	0	170	0
3	Dark Cyan	0	168	168
4	Dark Red	186	6	6
5	Dark Magenta	168	0	168
6	Orange	230	126	34
7	Light Gray	168	168	168
8	Dark Gray	85	87	83
9	Light Blue	87	87	255
10	Light Green	85	255	85
11	Light Cyan	96	240	240
12	Light Red	255	85	85
13	Light Magenta	240	84	240
14	Yellow	244	242	54
15	White	255	255	255

Packed Color Encoding

Several element types — Button, Input, and Checkbox — have both a border/outline color and a fill/background color. Rather than taking two separate color parameters, these elements accept a single packed byte where each nibble holds one palette index. The encoding is:

0xHF
  │└── Low nibble  (L): fill / background color index (0–15)
  └─── High nibble (H): border / outline color index  (0–15)

Two C macros defined in main.cc extract each nibble:

#define L(b)   ((b) & 0x0F)        // low nibble  → fill color
#define H(b)  (((b) >> 4) & 0x0F)  // high nibble → border color

Examples:

Packed value	Border (H)	Fill (L)	Result
`0x07`	0 — Black	7 — Light Gray	Black border, light gray fill
`0xF0`	15 — White	0 — Black	White border, black fill
`0x2A`	2 — Dark Green	10 — Light Green	Dark green border, light green fill

Pass packed values wherever a Button, Input, or Checkbox API asks for a color with both border and background behavior:

// Button with: unpressed = black border + light gray fill (0x07)
//              hover     = white border + dark gray fill   (0xF8)
//              pressed   = white border + black fill       (0xF0)
GCreateButton(0, 50, 50, 120, 30, 0x07, 0xF8, 0xF0, "Click me", on_click);

Rect’s fg and bg parameters are plain palette indices, not packed bytes. Use -1 for either to skip drawing that layer. Only Button, Input, and Checkbox use the packed nibble encoding.

Runtime Palette Modification

The palette is stored as live X11 color cells, so changes take effect immediately on the next rendered frame.

`GPaletteModify`

void GPaletteModify(int idx, unsigned char r, unsigned char g, unsigned char b, int redraw);

Replaces palette entry idx with the given RGB values. The existing color cell is freed and a new one is allocated in the X11 colormap. If redraw is nonzero, all image elements are immediately redrawn so their pixel data reflects the new color mapping.

`GPaletteQuery`

void GPaletteQuery(int idx, unsigned char* r, unsigned char* g, unsigned char* b);

Reads the current RGB components of palette entry idx back from the X11 colormap into the provided output pointers. Values are in the range 0–255.

`GPaletteReset`

void GPaletteReset();

Frees all 16 current color cells, re-allocates them from the hard-coded defaults in color_palette[], and calls GRedrawAllImages to refresh every image element. Use this to restore the palette after experimental modifications.

Example — replace Orange with pure red

// Change palette index 6 (Orange by default) to pure red,
// and redraw all image elements to reflect the change.
GPaletteModify(6, 255, 0, 0, 1);

// Later, verify the stored value:
unsigned char r, g, b;
GPaletteQuery(6, &r, &g, &b); // r=255, g=0, b=0

// Restore everything to defaults when done:
GPaletteReset();

Image elements store each pixel as a palette index, not a resolved RGB value. Changing a palette entry with GPaletteModify therefore affects every pixel across every canvas that uses that index. If you call GPaletteModify(6, 255, 0, 0, 1), all orange pixels in all image elements instantly become red. Design your palette usage carefully if multiple image elements must maintain independent color schemes.

Get Started

Core Concepts

Guides

LWXGL Color Palette: 16-Color System and Runtime Editing

Default Palette

Packed Color Encoding

Runtime Palette Modification

`GPaletteModify`

`GPaletteQuery`

`GPaletteReset`

Example — replace Orange with pure red

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​Default Palette

​Packed Color Encoding

​Runtime Palette Modification

​GPaletteModify

​GPaletteQuery

​GPaletteReset

​Example — replace Orange with pure red

Build docs developers (and LLMs) love

Default Palette

Packed Color Encoding

Runtime Palette Modification

`GPaletteModify`

`GPaletteQuery`

`GPaletteReset`

Example — replace Orange with pure red