# Choosing colors in Pliro

[Programming guides](README.md)

You can name a color, such as `"red"`, or describe its recipe with a code such as `"#ff0000"`.

## RGB and hexadecimal color codes

**RGB** stands for *red, green, blue*: three colors of light a screen mixes. Each part, called a **channel**, has a strength from 0 to 255. All three at 0 make black; all three at 255 make white.

**Hexadecimal**, or *hex*, writes numbers with sixteen digits: `0`–`9`, then `a`–`f` for ten through fifteen. A pair of hex digits can describe 0 through 255: `00` is 0 and `ff` is 255. In `#RRGGBB`, the pairs describe red, green, and blue. `"#ff0000"` therefore means full red with no green or blue. In the short `#RGB` form, each digit is doubled: `"#f80"` becomes `"#ff8800"`.

These colors are **opaque**: you cannot see through them. An **alpha channel** would describe transparency, but it is not part of these portable color formats. **Portable** means the same color format works across Pliro's supported drawing environments.

## Functions and named colors

| English call | Canonical ID | Returns |
|---|---|---|
| `clearCanvas(color)` | `graphics.clear` | `None` |
| `rectangle(x, y, width, height, color)` | `graphics.rectangle` | `None` |
| `circle(x, y, radius, color)` | `graphics.circle` | `None` |
| `drawLine(x1, y1, x2, y2, width, color)` | `graphics.line` | `None` |
| `drawText(x, y, content, size, color)` | `graphics.text` | `None` |
| `drawText(x, y, content, size, color, font)` | `graphics.text` | `None` |
| `drawText(x, y, content, size, color, font, align)` | `graphics.text` | `None` |

Coordinates and sizes are finite `Number` values. A circle radius, line width,
and text size must be positive. `drawText` content and colors must be `Text`,
and colors must not be empty. The following English and Dutch color names work
in **every syntax locale**, with the same RGB values across hosts:

| English | Dutch | RGB |
|---|---|---|
| `black` | `zwart` | `#000000` |
| `white` | `wit` | `#ffffff` |
| `red` | `rood` | `#ff0000` |
| `green` | `groen` | `#008000` |
| `blue` | `blauw` | `#0000ff` |
| `yellow` | `geel` | `#ffff00` |
| `cyan` | `cyaan` | `#00ffff` |
| `magenta` | `magenta` | `#ff00ff` |
| `orange` | `oranje` | `#ffa500` |
| `purple` | `paars` | `#800080` |
| `pink` | `roze` | `#ffc0cb` |
| `gray`, `grey` | `grijs` | `#808080` |
| `brown` | `bruin` | `#a52a2a` |

Names ignore ASCII letter case and surrounding [Unicode](../concepts/unicode.md) whitespace. `#RGB` and
`#RRGGBB` are also portable, with case-insensitive hexadecimal digits; `"#f80"`
means `"#ff8800"`. These formats are opaque and contain no alpha channel.
Color names are ordinary text values and remain unchanged during syntax
conversion. For example, English `circle(100, 100, 30, "rood")` is valid.

The 2D runtime normalizes supported names to canonical English color names.
Other non-empty 2D color text passes through, but arbitrary CSS colors and
alpha forms are host-dependent. The 3D APIs accept only the portable names and
hex formats above and normalize them to lowercase `#rrggbb`. See the
[portable color specification](../../../docs/spec/colors.md).

The runtime currently accepts any finite rectangle dimensions; portable
programs should use positive width and height.

`drawText` accepts these optional values:

| Parameter | Values | Default |
|---|---|---|
| `font` | `"sans"`, `"pixel"` | `"sans"` |
| `align` | `"left"`, `"center"`, `"right"` | `"left"` |

Font and alignment names are trimmed and case-insensitive. The x coordinate is
the selected horizontal alignment anchor. The y coordinate is the top of the
line box. Pliro embeds its pinned Sans and Pixel fonts so graphical builds do
not depend on installed system fonts.

## Other words on this page

**Normalizing** means storing equivalent spellings in one agreed form: `"ROOD"` and `"red"` name the same color. **CSS** (*Cascading Style Sheets*) describes the appearance of web pages and has more color formats; that does not mean every Pliro host can use all of them. **Whitespace** means spaces and similar spacing characters around a name.

A **font** is a style of letters. `"sans"` uses the Sans font; `"pixel"` uses the blocky Pixel font. **Alignment** tells Pliro which part of the text sits at x: its left edge, center, or right edge. This chosen point is the **anchor**. The **line box** is the space reserved for a line of text; y marks its top. **Bundled fonts** come with Pliro, so you do not need to install them yourself.

## Related entries

[Syntax and values](../syntax/README.md) · [Built-ins](../builtins/README.md) · [Programming guides](README.md)