PaletteV

 Title: PaletteV
 Author: Tim Dobson
 History:
        11-Nov-91 TMD Adapted from ColourTrans.Doc.PaletteV
        25-Nov-91 TMD Changed a bit about setting flashing colours

From RISC OS 3.03 onwards, the kernel has a default entry on PaletteV. Also,
a number of additional reason codes have been added, to facilitate the
implementation of the LCD drivers for Perth.

The new specification for PaletteV is as follows:-

R4 holds a reason code on entry to the vector. Any owner of the vector which
has carried out the operation requested should set R4 to zero and claim the
vector.

 Reason codes
 ============

        1 - Read palette

        in:     R0 = logical colour
                R1 = type of colour (16,17,18,24,25)
                R4 = 1 (reason code)

        out:    R2 = 1st flash colour (&BBGGRRSS) - device colour
                R3 = 2nd flash colour (&BBGGRRSS) - device colour
                R4 = 0 => operation complete

        2 - Set palette

        in:     R0 = logical colour
                R1 = type of colour (16,17,18,24,25)
                R2 = &BBGGRRSS - device colour
                R4 = 2 (reason code)

        out:    R4 = 0 => operation complete

        3 - Set first flash state

        in:     R4 = 3 (reason code)

        out:    R4 = 0 => operation complete

        4 - Set second flash state

        in:     R4 = 4 (reason code)

        out:    R4 = 0 => operation complete

        5 - Set default palette

        in:     R4 = 5 (reason code)

        out:    R4 = 0 => operation complete

        6 - Blank/unblank screen (only available from RISC OS 3.08 onwards)

        in:     R0 = -1 (read blank state)
                   or 0 (unblank screen)
                   or 1 (blank screen)
                R4 = 6 (reason code)

        out:    R0 = old state (0=unblanked, 1=blanked)
                R4 = 0 => operation complete

        This call blanks or unblanks the screen, independently of the current
        palette settings.

In the SS bits mentioned in calls 1 and 2 above, bit 7 is the current
supremacy bit, other bits are reserved.

 How old OS calls map onto PaletteV
 ----------------------------------

Initial suggestions were that VDU 19 and OS_Word(12) should ignore the
bottom 4 bits of RGB values passed to them, and duplicate the top 4 bits in
the bottom 4 bits before calling PaletteV. This was so that old style
programs which set the low nybbles to zero would work correctly on machines
with 8-bit per gun palette hardware.

However, I believe that this damages the usefulness of the above calls
unnecessarily. As long as the default palettes read back true 8-bit values,
and the PaletteUtil module duplicates the nybbles when setting the colours,
it should not be necessary to alter the parameters to VDU 19 and
OS_Word(12).

So the OS will pass the values through to PaletteV, and, assuming there is
no-one else on the vector, will get the values itself. At this point it will
just store the top 4 bits of each value in its soft copy, and in the
hardware if appropriate (when setting the 1st and 2nd flashing colours it
only updates the hardware if that flash state is current).

The calls to read the palette on earlier versions of the OS return a value
which corresponds to how the palette entry was programmed, ie 0..15 if a BBC
style colour was selected, 16 if steady RGB colours were used, 17 or 18 for
flashing colours, 24 for border colours and 25 for pointer colours.

Since PaletteV does not return this information, the OS will try to make up
this information itself. It can easily cope with the 24,25 cases. If the two
colours returned are different, it will substitute 17 or 18 as appropriate,
otherwise it will use 16. It will no longer return values in the range 0 to
15.

Also, when setting the palette, PaletteV does not understand BBC colours
0..15. In order to provide the necessary functionality, the OS calls to set
the palette will trap these values and convert them to type 16 calls (for
0..7) or pairs of type 17 and type 18 calls.

This requires a slight change to the specification of what type 17 and 18
calls do. At the moment, these calls NEVER update the VIDC palette, instead
they only update the relevant soft copy, and when/if the flash state
changes, the colours are updated. But programming a BBC flashing colour
takes effect immediately even if the flash state is 'frozen'.

I therefore propose to make the 17 and 18 calls also update the VIDC palette
if the current state is 1st or 2nd respectively. It's still not quite ideal
because you really want to update both flash colours atomically, in case the
state changed in between the two calls.