The ColourTrans Module

This module is not part of the ROM, but is in !system.modules.colours in the Welcome Suite. It provides generally useful functionality, and so it is documented as part of RISC OS.

Throughout, a mode of -1 means the current mode, and a palette pointer of 0 means the default palette (i.e. the palette set by the MOS on entry to the specified mode).
-1 as a palette pointer refers to the current palette; this is generally only sensible if -1 is specified for the mode.

"Palette pointer" (from here on just "palette") means a pointer to a list of words, containing BBGGRRxx. In 256 colour modes only the first 16 of these are be referenced, real colours being built from there.

When the destination is a 256 colour mode, "GCOL" means a byte with the real GCOL in bits 2-7, and the tint in bits 0 & 1.

"Colour number" is used to refer to the byte that's placed into screen memory; identical to the GCOL except for 256 colour modes.

"Most different" means "maximises the distance function"; "closest" means "minimises the distance function". The distance function is a weighted least squares, i.e.
where colours are (Rs, Gs, Bs) and (Rd, Gd, Bd)

distance = redweight*(Rs-Rd)^2 +

               greenweight*(Gs-Gd)^2 +
                blueweight*(Bs-Bd)^2.

Currently, blueweight = 1, redweight = 2, greenweight = 3; this seems to give acceptable results on the limited problem we are tackling.

SWIs:

ColourTrans_SelectTable (&40740)

Given a source mode & palette, and destination mode & palette, and a buffer, set up a translation table in the buffer. ("Translation table" means a set of colour numbers as used by the scaled sprite plotting).

and ColourTrans_SelectGCOLTable (&40741)

Given a source mode & palette, and destination mode & palette, and a buffer, set up a list of GCOLs in the buffer.

For both the above:
Input: r0 = source mode
r1 = source palette
r2 = destination mode
r3 = destination palette
r4 = buffer (assumed to be long enough,

                     i.e. no_of_colours(source mode) bytes long)

ColourTrans_ReturnGCOL (&40742)

Given a palette entry (BBGGRRxx), return the closest GCOL in the current mode and palette. Input: r0 = palette entry
Output: r0 = GCOL

ColourTrans_SetGCOL (&40743)

Given a palette entry, return the closest GCOL in the current mode and palette, and also set the GCOL. Input: r0 = palette entry
r3 = 0 or 128 for fore/background
r4 = GCOL action
Both r3 and r4 should have the top three bytes clear, to allow
for future expansion.
Output: r0 = GCOL

ColourTrans_ReturnColourNumber (&40744)

Given a palette entry (BBGGRRxx), return the closest colour number in the current mode and palette. Input: r0 = palette entry
Output: r0 = colour number

ColourTrans_ReturnGCOLForMode (&40745)

Given a palette entry, a destination mode and palette, return the closest GCOL. Input: r0 = palette entry
r1 = destination mode
r2 = destination palette
Output: r0 = GCOL

ColourTrans_ReturnColourNumberForMode (&40746)

Given a palette entry, a destination mode and palette, return the closest colour number. Input: r0 = palette entry
r1 = destination mode
r2 = destination palette
Output: r0 = colour number

ColourTrans_ReturnOppGCOL (&40747)

ColourTrans_SetOppGCOL (&40748)
ColourTrans_ReturnOppColourNumber (&40749)
ColourTrans_ReturnOppGCOLForMode (&4074A)
ColourTrans_ReturnOppColourNumberForMode (&4074B)
Parameters are exactly the same as 40742-40746; action is very similar, but the furthest rather than closest colour is returned.

ColourTrans_GCOLToColourNumber (&4074C)

Translate a GCOL to a colour number (assuming a 256 colour mode is meant). Input: r0 = GCOL
Output: r0 = colour number

ColourTrans_ColourNumberToGCOL (&4074D)

Translate a colour number to a GCOL (assuming a 256 colour mode is meant). Input: r0 = colour number
Output: r0 = GCOL

ColourTrans_ReturnFontColours (&4074E)

ColourTrans_SetFontColours (&4074F)
Input: r0 = font handle
r1 = background palette entry
r2 = foreground palette entry
        r3 = max offset

Output: r0-r3 as passed to Font_SetFontColour

This returns font colours to match the given colours; the closest approximation to the foreground and background will be set, and as many intermediate colours (up to the specified maximum) as can be done.

ColourTrans_SetFontColours also calls Font_SetFontColours. Note: in 256 colour modes, only 16 font colours can be set up before
previously returned information becomes invalid. Therefore, if using ReturnFontColours to obtain information to insert in a string to pass to the font painter, do not allow more than 16 distinct colours in the string.

ColourTrans_InvalidateCache (&40750)

This call must be issued whenever the palette has changed since ColourTrans was last called. Note that palette changes due to mode change are detected by the module.