== Palette and Scanline Control

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

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

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

=== jlPaletteSet

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

Loads all 16 colours 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 colours of one palette.

[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, 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.