Tool translation tables
=======================
Design
------
Tools sprite designers can optionally provide a set of precalculated translation tables to map the toolsprites onto the standard 16 Wimp colours.

Historically toolsprites have relied on one of two methods to adapt the sprite designs to match the application programmer's template colour choices:
a) Scatter some transparent pixels through the toolsprites so that the
   underlying Wimp solid fill leaks through.
b) From Ursula onwards, if the toolsprite is 256 colours or less and solid,
   then the Wimp will tint grey (R=G=B) portions of the titlebar sprites
   with the underlying Wimp solid fill colour. The 'colourmoreborder' switch
   applied tinting to the other highlighted elements (back, close, iconise,
   toggle, adjust, arrows) but the code is disabled on aesthetic grounds. 

These schemes have some drawbacks:
 - designers don't want to have transparency because it is binary and
   therefore gives tools a spotty dithered look
 - solid tools may not be tinted in the designer's desired style
 - solid tools may by default themselves be tinted, and therefore not grey,
   and therefore the tinting doesn't apply anyway
 - resulting in the solid tool obliterating the template's colour choice, for
   example writable menus are grey 2 by default, rather than the cream 12
   that might be inferred if only considering input focus status

Though alpha blending may appear to be one solution, the situation where alpha blending is also used to make the window itself translucent would result in two computationally expensive operations - blending the template colour choice with the tool sprite, then blending the result with the underlying desktop.

To mitigate these drawbacks the template designer can supply precalculated custom colour translation tables alongside the toolsprites.

It is generally assumed that within a tool set the variants will infact all be the same basic design and that the variations are mainly in their colouring. One way to think of this is the sprites provide a clay mould and the translation tables supply details of which paints to use - a more space efficient solution than providing 16 complete paletted sprite sets.

As a guide, there are about 35000 pixels in a 90x90 set, so providing EX1 EY1
and EX1 EY2 sets would be approximately:

  Colour space                      90x45  + 90x90   Total
  4bpp+individual palette           15.7k  + 24.9k   40.6k
  8bpp+desktop palette              18.5k  + 37k     55.5k
  8bpp+individual palette           118.5k + 137k    255.5k
  16bpp                             37k    + 74k     111k
  32bpp                             74k    + 148k    222k
  A typical 2 table scheme (2k)     18.5k  + 37+2k   57.5k
  A fully tabled scheme (17k)       18.5k  + 37+17k  72.5k

While 32K and 16M colour tables could in future be supported, their large table size is likely to make them of limited use. Therefore this scheme will use 256 entry tables - note that that's 256 colours from a 16M colour palette for each of the toolsprite elements that can be coloured
  1. Title bar and gadgets
  2. Scroll bar inner
  3. Scroll bar outer
  4. Elements with input focus

which is up to 1024 colours on screen in total (for 8bpp and lower obviously the hardware is the limiting factor). This is likely to deal even the most complex of design arrangements. 

Details
-------
Each table is containerised as a sprite, a 16x16 in 16M colours is suggested since that can then be viewed in !Paint, but not required - any 256 word sized sprite will do.

The 'extension area' of the sprite file format was considered, but this is often stripped by editors, making it difficult to visualise. Sprites can be designed using !Paint and the palettes removed at the final step (which will make them appear in "false colour" usually - remember to keep the originals!).

Encoding the table in a palette of a (eg.) 1x1 sprite was also considered, but the inclusion of flashing colours in sprite palettes made this method wasteful.

The table(s) are named
  table_<wimpcolour>

following the same naming scheme as the optional window background textures. A simple set might contain
  table_2       (for sc_lightgrey)
  table_12      (for sc_cream)

A fully specified set would be 16k in total, one for each of the 16 Wimp colours.

Where no tables are provided, behaviour described in (a) and (b) above will prevail, using a default translation table from ColourTrans_GenerateTable.

Where a need to plot a tinted border occurs (see 'colourmoreborder') if the tint colour matches one of the standard Wimp colours that will be used, where no specific table has been supplied table_2 will be used. First, the colours will be forcefully greyscaled, then the tinting algorithm from (b) applied.
If this jars particularly with the designers aim, a full set of tables should be provided instead so the tinting is then only needed for the rare situation of a non standard true colour being chosen (using the 'C' validation string).

Where a need to plot a non tinted border occurs if the colour required matches one of the standard Wimp colours that will be used, where no specific table has been supplied table_2 will be used.

Plotting
--------
As stated earlier, 256 translation table entries each of 32b are provided for. Plotting these into
  1bpp  => table reduced into 256B form at 1bpp via ColourTrans
  2bpp  => table reduced into 256B form at 2bpp via ColourTrans
  4bpp  => table reduced into 256B form at 4bpp via ColourTrans
  8bpp  => table reduced into 256B form at 8bpp via ColourTrans
  16bpp => table reduced into 512B form at 16bpp via ColourTrans 
  32bpp => uses table provided directly

Calibration
-----------
Translation tables are not currently (re)calibrated.
