InverseTable
------------

Inverse table provides 8bpp translation tables for graphical applications.
Because converting between 8bpp values and providing a mechanism to 'blend'
between these is time consuming, the InverseTable module provides core
functions to calculate the tables involved.

The module will generate two tables :
  * A RGB to colour number lookup table
  * A colour number to RGB lookup table

Because producing a full range RGB table would be a little extreme
(requiring 16 M of RAM to store it) the tables are generated at 5 bit
accuracy. Applications requiring greater accuracy than this in 8bpp modes
may wish to use alternate means to perform their blending.

The RGB to colour number lookup table is a table of 32768 byte values
which correspond to the relevant colour. To calculate the index into
the table of the colour number closest an RGB value, the RGB value should
first be quantised to 5 bits per component. The values should then be
laid out as follows :

  Bits  Component
  0-4   Red
  5-9   Green
  10-14 Blue

The resulting value can then be used as an index into the RGB to colour
number table.

The colour number to RGB lookup table is a table of 256 4-byte wide word
values. Because the tables are used for speed, rather than for space,
the values are not packed. The value read follows the same bit layout
described above.

Example:

REM Fade a colour to half its brightness via the inverse tables
REM colour% is a colour number
:
SYS "InverseTable_Calculate" TO rgbtable%,colourtable%
rgb%=rgbtable%!(colour%*4)
:
REM Now transform the colour (halve it and clear the shifted bits)
rgb%=rgb%>>1
rgb%=rgb% AND NOT ((1<<4) OR (1<<9))
REM We now have :
REM   %0BBBB0GGGG0RRRR
:
colour%=colourtable%?rgb%
REM colour% is the half brightness value


InverseTable_Calculate
<= R0 = pointer to 5,5,5 RGB lookup table (colour number to RGB)
   R1 = pointer to colour number lookup table (RGB to colour number)

This SWI calculates a suitable pair of tables for the current destination
(screen, or sprite). The tables are guarenteed to be static until the next
mode change service is issued. Where necessary, the tables will be
recalculated. This may take a number of seconds and so the hourglass will
be displayed whilst this takes place. Precalculated tables may be used
by the module for certain common palettes (presently, only the standard
256 colour palette is catered for in this manner). Where the table is
already calculated, InverseTable will return the table values without
recalculating them. Recalculation will be forced if the palette changes.
Recalculation may take around two seconds on a StrongARM based machine, or
around seven on an ARM 610 based machine.


InverseTable_SpriteTable
=> R0 = pointer to 5,5,5 RGB lookup table (colour number to RGB)
        (1024 bytes)
   R1 = pointer to colour number lookup table (RGB to colour number)
        (32768 bytes)
   R2 = sprite area to use, or mode number (equivilent to parameter R0 to
        ColourTrans_ReadPalette)
   R3 = sprite pointer to use (equivilent to paramter R1 to
        ColourTrans_ReadPalette)
<= R0 = pointer to 5,5,5 RGB lookup table (colour number to RGB)
   R1 = pointer to colour number lookup table (RGB to colour number)

This SWI calculates a suitable pair of tables for an arbitrary sprite.
If the table has not been cached, it will be recalculated. If the table
has been cached, R0 and R1 on exit may differ from those passed in. Where
the destination is the current mode, it is strongly recommended that you
call InverseTable_Calculate rather than this SWI as this will retain a
cache of the table data.
