# Color encodings

The library at gr/color.fs defines color encoding as well as encoding/decoding
words for them.

At the moment, there's only one supported color encoding, so it has little logic.
It's mostly a placeholder for a fancier color management library.

## Bits layouts and endianness

The encoding defined here are "above" endianness. We refer to pure 32-bit
numbers (we don't support encodings above 32bit), regardless of encoding. When
we refer to bits in the memory layouts described below, we refer to the bits in
the "pure" number, bit 31 being the most significant bit and bit 0 being the
least significant bit.

We expect drivers dealing with those colors to be endianness aware and deal
with writing the correct color in the correct endianness themselves.

Let's use the example of the 24bpp VESA mode. Because it runs on a i386
architecture, it's always going to deal with little endian. So, if we say that
Red is b23:16, Green is b15:8 and Blue is b7:0, then we know that this means
that for a given address "a", Red is the byte at a+2, Green is at a+1 and Blue
is at a+0.

Let's imagine that we manage the same memory layout from a big endian
architecture. Then, the driver will have to deal with it. Either it's going to
specify that its supported color is another encoding (one that has RGB reversed)
or it takes care, when reading and writing those colors, to reverse those bytes.

## Color encoding list

COLOR_RGB565
  16-bit RGB encoding with Red=b15:11 Green=b10:5 Blue=b4:0
COLOR_RGB555
  16-bit RGB encoding with Red=b14:10 Green=b9:5 Blue=b4:0
COLOR_RGB888
  24-bit RGB encoding with Red=b23:16 Green=b15:8 Blue=b7:0

## API

colorbpp ( id -- bpp )
  Returns the bpp (bits per plane) value, that is, the number of bits that each
  pixel of that encoding takes, for the specified encoding ID.

colorbytes ( id -- n )
  colorbpp divided by 8.

colorwriter ( id -- w )
  Yields an appropriate "writer" word with a signature ( color a -- color a+ )
  which writes color to a and then yields a+<byte size of color>.

  We keep the color around for performance reasons. If the same color has to be
  written multiple times, it's faster, and even if the color changes, it's
  faster for the HAL to set PSP+0 than to push a value back.

  Words yielded here are guaranteed to preserve the A register.

The words below all convert 3 8-bit RGB components into a specific encoding:

>rgb565 ( r8 g8 b8 -- n )
>rgb555 ( r8 g8 b8 -- n )
>rgb888 ( r8 g8 b8 -- n )

And there are also faster re-encoding words that don't require splitting a color
in 3 components:

rgb888>rgb565 ( n -- n )
