120 lines
2.9 KiB
Text
120 lines
2.9 KiB
Text
== 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.
|