149 lines
4.3 KiB
Text
149 lines
4.3 KiB
Text
== 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.
|