![[Burning Cog]](../../../icons/pyromaniac.png){kind=icon}
Introduction and Overview
The InverseTable module provides a fast mapping between 8bpp palette entries and reduced 5:5:5 RGB colour values. It is intended for clients that need to convert colours repeatedly when rendering or compositing paletted graphics.
The module supplies two SWIs. SWI InverseTable_Calculate returns tables for the current screen mode, and SWI InverseTable_SpriteTable returns equivalent tables for a sprite palette. Both interfaces are only valid for 8bpp palettes.
These tables are commonly used by modules which need to blend, remap, or quantise paletted colours without performing a full nearest-colour search for every pixel.
Technical Details
InverseTable exposes two related tables:
- An index-to-5:5:5 table, addressed by palette index and returning a 32-bit word containing a packed 5:5:5 RGB value.
- A 5:5:5-to-index table, addressed by a packed 5:5:5 RGB value and returning the nearest palette index as a byte.
5:5:5 RGB format
The packed RGB values use 15 significant bits, arranged as:
bit 14..10 Blue bit 9.. 5 Green bit 4.. 0 Red
The value returned by the index-to-5:5:5 table can be used directly as an index into the 5:5:5-to-index table.
Mode restrictions
Both SWIs require a palette with 256 entries. Calls made for non-8bpp screen modes or sprite palettes report the standard Bad MODE error.
Caching
The module may return pointers to cached tables rather than rebuilding them on every call. Clients must therefore treat the returned memory as module-owned and read-only.
SWI Calls
| R0 - R9 | preserved | |
| R0 | = | Pointer to the index-to-5:5:5 RGB table |
| R1 | = | Pointer to the 5:5:5 RGB-to-index table |
This SWI returns pointers to the tables for the current screen palette. If the cached tables are invalid, they are recomputed before the pointers are returned.
The index-to-5:5:5 RGB table contains 256 words. The 5:5:5 RGB-to-index table contains 32768 bytes, one for each possible 15-bit RGB value.
This SWI is only valid when the current screen mode is 8bpp. In other modes the call reports Bad MODE. If the SWI reports an error, R1 is not preserved.
| R0 | = | Pointer to a caller-supplied index-to-5:5:5 table buffer, or 0 |
| R1 | = | Pointer to a caller-supplied 5:5:5-to-index table buffer, or 0 |
| R2 | = | Sprite area, as for R0 of SWI ColourTrans_ReadPalette |
| R3 | = | Sprite pointer, as for R1 of SWI ColourTrans_ReadPalette |
| R0 | = | Pointer to the index-to-5:5:5 table. This may differ from the value supplied on entry if a cached table is returned. |
| R1 | = | Pointer to the 5:5:5-to-index table. This may differ from the value supplied on entry if a cached table is returned. |
This SWI returns tables for a particular sprite palette instead of the current screen palette. The sprite and sprite area are interpreted using the same conventions as the palette-reading interfaces.
If cached tables already exist for the requested palette, the module may return those cached pointers instead of using the caller's supplied buffers.
As with SWI InverseTable_Calculate, this SWI is only valid for 8bpp palettes.
Examples
The following BASIC example obtains the tables for the current 8bpp screen mode:
MODE 28 SYS "InverseTable_Calculate" TO to555%, from555% PRINT "Index 0 maps to &"; ~to555%!0 PRINT "Nearest index for 5:5:5 value 0 is "; ?from555%
The returned word from to555% may be used directly as an index into the byte table at from555%.