== Palette and Scanline Control

Declared in `<joey/palette.h>`.

Colors are 12-bit `$0RGB`: bits 11..8 red, 7..4 green, 3..0 blue. Each surface
holds 16 palettes of 16 colors, plus a 200-entry table (the SCB table) naming
which palette each scanline uses. That is how a JoeyLib program shows more than
16 colors at once.

[IMPORTANT]
====
Color 0 of every palette is black, always. `jlPaletteSet` silently masks entry
0 to `$000` whatever you pass, and `jlSurfaceLoadFile` does the same to every
palette it loads. This is deliberate: the Amiga and ST hardware border follows
color 0 of the active palette, and color 0 is the transparent color for
sprite drawing. You have 15 usable colors per palette.
====

Palette and SCB changes to the stage reach the display at the next
`jlStagePresent`, not before. Out-of-range arguments are ignored
the same way on every port: a palette index above 15 or a line above 199 makes
the setters do nothing (`jlScbSetRange` stops its range at line 199), and
`jlScbGet` returns 0 for a line off the surface.

=== The Default Palette

Every surface starts with all 16 of its palettes set to the standard 16 EGA
colors, and every line of its SCB on palette 0: the stage at `jlInit`, and a
surface at `jlSurfaceCreate`. A program that never calls `jlPaletteSet` draws
in these colors:

[cols="1,2,1,1,2,1", options="header"]
|===
|Index |Color |`$0RGB` |Index |Color |`$0RGB`
|0 |Black         |`$000` |8  |Dark gray     |`$555`
|1 |Blue          |`$00A` |9  |Light blue    |`$55F`
|2 |Green         |`$0A0` |10 |Light green   |`$5F5`
|3 |Cyan          |`$0AA` |11 |Light cyan    |`$5FF`
|4 |Red           |`$A00` |12 |Light red     |`$F55`
|5 |Magenta       |`$A0A` |13 |Light magenta |`$F5F`
|6 |Brown         |`$A50` |14 |Yellow        |`$FF5`
|7 |Light gray    |`$AAA` |15 |White         |`$FFF`
|===

=== jlPaletteSet

[source,c]
----
void jlPaletteSet(jlSurfaceT *s, uint8_t paletteIndex, const uint16_t *colors16);
----

Loads all 16 colors of one palette.

[cols="1,1,4", options="header"]
|===
|Parameter |Type |Description
|`s` |`jlSurfaceT *` |Target surface.
|`paletteIndex` |`uint8_t` |Which palette, 0..15.
|`colors16` |`const uint16_t *` |Exactly 16 `$0RGB` values. Entry 0 is forced
 to `$000` regardless of what you supply.
|===

*Returns:* nothing.

=== jlPaletteGet

[source,c]
----
void jlPaletteGet(const jlSurfaceT *s, uint8_t paletteIndex, uint16_t *out16);
----

Reads all 16 colors of one palette, as they were set: the values passed to
`jlPaletteSet` (with entry 0 forced to `$000`, and bits 12 to 15 kept as
passed), not what the display can show of them.

[cols="1,1,4", options="header"]
|===
|Parameter |Type |Description
|`s` |`const jlSurfaceT *` |Source surface.
|`paletteIndex` |`uint8_t` |Which palette, 0..15.
|`out16` |`uint16_t *` |Receives 16 `$0RGB` values. Caller-owned, and must have
 room for all 16.
|===

*Returns:* nothing.

=== jlScbSet

[source,c]
----
void jlScbSet(jlSurfaceT *s, uint16_t line, uint8_t paletteIndex);
----

Assigns a palette to a single scanline.

[cols="1,1,4", options="header"]
|===
|Parameter |Type |Description
|`s` |`jlSurfaceT *` |Target surface.
|`line` |`uint16_t` |Scanline, 0..199.
|`paletteIndex` |`uint8_t` |Palette to use on that line, 0..15.
|===

*Returns:* nothing.

=== jlScbSetRange

[source,c]
----
void jlScbSetRange(jlSurfaceT *s, uint16_t firstLine, uint16_t lastLine,
                   uint8_t paletteIndex);
----

Assigns a palette to an inclusive range of scanlines. The usual way to set up a
screen, whether that is one palette everywhere or several horizontal bands.

[cols="1,1,4", options="header"]
|===
|Parameter |Type |Description
|`s` |`jlSurfaceT *` |Target surface.
|`firstLine` |`uint16_t` |First scanline, inclusive.
|`lastLine` |`uint16_t` |Last scanline, inclusive.
|`paletteIndex` |`uint8_t` |Palette to use, 0..15.
|===

*Returns:* nothing.

[source,c]
----
// Sky on the top third, ground below, using two palettes.
jlScbSetRange(stage, 0, 65, 0);
jlScbSetRange(stage, 66, JL_SURFACE_HEIGHT - 1, 1);
----

=== jlScbGet

[source,c]
----
uint8_t jlScbGet(const jlSurfaceT *s, uint16_t line);
----

[cols="1,1,4", options="header"]
|===
|Parameter |Type |Description
|`s` |`const jlSurfaceT *` |Source surface.
|`line` |`uint16_t` |Scanline, 0..199.
|===

*Returns:* the palette index assigned to that scanline.