> scsi::Reality.New.Colours.SWIS

Title; ColourTrans Extensions
Created; 28-May-91
Late updated: 20-Jan-92
Author; David De Vorchik (dizzy@acorn.co.uk)
History;
        28-May-91 DDV Created
        29-May-91 DDV Extened ColourTrans_WritePalette for single entries
        07-Jun-91 DDV Note aboute switching output to a sprite
        05-Aug-91 DDV Updated notes on switching output to sprite
        05-Aug-91 DDV Added some comments on true colour sprites
        07-Aug-91 DDV Added ColourTrans_SetColour
        22-Aug-91 DDV Added ColourTrans_MiscOp
        26-Aug-91 DDV Updated specification of ColourTrans_SelectTable
        26-Aug-91 DDV Updated specification of ColourTrans_Read/WritePalette
        06-Sep-91 DDV Added information on MiscOp_ReturnPattern
        06-Sep-91 DDV Removed reference to 256 colour sprites
        08-Sep-91 DDV Added note on Service_InvalidateCache
        17-Oct-91 DDV Note on reading the size of tables from SelectTable
        21-Oct-91 DDV Added note on WriteLoadingsToFile SWI
        02-Dec-91 DDV Added ColourTrans_Set[Opp]TextColour
        02-Dec-91 DDV Change to ColourTrans_SetColour (bit 9 of flags)
        14-Jan-92 DDV Updated to ColourTrans_SelectTable to reflect reality.
        20-Jan-92 DDV Updated again to be more in-line with RO-3.05.

ColourTrans_SelectTable / ColourTrans_GenerateTable
---------------------------------------------------

        in:  R0 source mode number / =-1 if current
             R1 ->source palette / =-1 for current / =0 for default for mode
             R2 destination mode / =-1 for current
             R3 ->destination palette / =-1 for current / =0 for default for mode
             R4 ->return table / =0 to return size of table

             IF R0 >= &100 THEN 

                    R0 -> sprite control block
                    R1 -> sprite name (or sprite if R5, bit 0 set)

                    R5 flags
                        bit 0 set => R1 -> sprite, not sprite name (if R0 >= &100)
                        bit 1 set => if sprite has no palette, use current instead of default
                        bit 2 set => R6 = workspace pointer for function
                                     R7 -> transfer function
 
                        bit 24-31 => return format of the table
                                        = 0 => return PixTrans table
                                        = 1 => return physical palette table
 
                            all other bits reserved
 
        out: as before, except when reading the size when R4 contains the size on exit

NB: ColourTrans_GenerateTable is the same as select table except that it
    always assumes that R5 contains a valid flags word.
        
Call extended to save the user having to copy palette information out from
sprite header before getting ColourTrans to translate it.  Also extended to
cope with full-256 colour palette sprites.
                 
The following calls redirect via PaletteV where required.  Also, when output
is switched to a sprite then all operations to read the palette read the
palette from the sprite.  But writing is not allowed. 
         
Note that R5 contains a flags word if R0 >255 and any stray bits within 
this word will be faulted.

R5 contains a flags word where bit 0 is used to control the meaining of
R1, when set this indicates that R1 is the pointer to a sprite rather
than the sprite name that has to be resolved.  Bit 1 is used to indicate
that if the sprite has no palette then perform a translation using the
current rather than the default for the mode.  
                                   
If bit 2 is set of the flags, then it is assumed that R6,R7 contain
information about the transfer function to be used.  R6 is the workspace
pointer that is passed in R12 to the routine and R7 is the pointer 
to the routine to call.  This routine is called for each palette
entry before it is converted to a colour number or what ever to allow
it to be processed, the colour word (&BBGGRR00) is passed in R) and
is expected back in R0.  The routine should preserve all registers.

Bits 24-31 contain the return format for the table, currently returning
only the PixTrans table and a palette table are supported.

These transfer functions allow the RGB to be remapped prior to it
being converted to a suitable colour number.


ColourTrans_ReadPalette
-----------------------

        in:  r0  = source of palette read
                        =  -1 for current mode
                        < 256 for specified mode
                        > 256 for -> sprite area

             r1  = palette block to be read
                     if r0 >= 256 then;
                        if r4,bit 0 =1 -> sprite
                        if r4,bit 0 =0 -> sprite name

                     if r0 < 256 then;
                        r1 =-1 read current palette
                           = 0 use default for mode
                           > 0 use palette table at r1 (single word entrie of &BBGGRRxx)
        
              r2 -> return buffer / =0 then return size only in r3
              r3  = size of return buffer if r2<>0
              r4  = flags word
                        bit 0 set => r1 -> sprite
                        bit 1 set => return flashing colours

        out: V clear;
                if r2 <>0 on entry then;
                        [r2] updated to contain the palette data in &BBGGRRxx format
                        r2 updated to point to next free word in buffer
                        r3 updated to contain remaining size in buffer

             V set, r0 -> error block.

In 256 colour modes then the palette is returned fully expanded, ie. 256
palette entries rather than the base 16 entries used by VIDC.

All palette entries are returned as TRUE 24bit RGB, passing through the
calibration if required.  When reading a 16 palette table through a 256
colour mode then it will be expanded using the original brain damaged
algorithm of munging the tint to make the extra information

This call is the suggested way of reading the palette in RISC OS, it
provides a way of for applications to enquire about the palette and always
read the absolute values no matter what the hardware is capabile of.



ColourTrans_WritePalette
------------------------

        in:  r0  = destination of palette write
                        =  -1 for current mode
                        >= 0 for sprite area

             r1  = palette block to write
                     if r0 >= 0 then;
                        if r4,bit 0 =1 => r1 -> sprite 
                        if r4,bit 0 =0 => r1 -> sprite name

                     if r0 = -1 then;
                        r1 =-1 write current palette 

             r2 -> table containing palette entries to write
             r3  = 0, reserved for future expansion
             r4  = flags word
                        bit 0 set => R1 -> sprite, not name
                        bit 1 set => flashing colours within table

       out: V clear; operation worked.
            V set; r0 -> error block.

This call is used to write palettes under RISC OS.  It allows writing to
both the screen and a sprite.

When writing a 256 colour palette then the module attempts to compact the
palette as much as possible.  This is done by seeing if compacting it and
expanding it using the tint information transfer will yeild the same
results, if so then the palette is stored in this compressed for, otherwise
it is stored in the expanded for of all 256 palette entries.


Switching output to sprites and its effect on ColourTrans
---------------------------------------------------------

ColourTrans now notices when output has been switched to a sprite,
it attempts to invalidate the cache when required (ie. output is
switched and a call is made to CTrans, but not if output is
switched and then restored).

If the sprite has a palette then ColourTrans will perform any colour
calculations based on the palette associated with that sprite.  If the
sprite does not have a palette then it uses the one for the current screen
mode rather than the default for that mode which would be correct, this is
because some spacko applications make assumptions about this.


ColourTrans and the PaletteV
----------------------------

ColourTrans now makes full use of PaletteV as described in the PaletteV
documentation, when implementing a replacement colour system simply
interceping the calls on PaletteV should ensure that colour matching
will be performed.

It should be noted however that when dealing with true 256 colour screen modes
that bit 7 of the mode flags should be set to indicate that the mode
has a full 256 palette entries, rather than the brain-damaged 16 entries
with tints.


ColourTrans_SetColour
---------------------

  Entry: R0 GCOL number
         R3 Flags; bit 7 set => set background, else foreground
                   bit 9 set => set text colour from GCOL
         R4 GCOL action
                    
  Exit:  V set   => R0 ->Error block
         V clear => all preserved.

This call changes the foreground/background colour to a value as
returned from ColourTrans_ReturnGCOL.  It should only be used for 
colour numbers returned for the current mode.

If bit 9 of the R3 flags word is set then the routine will modify
the text colours rather than the graphics.


ColourTrans_MiscOp
------------------

  Entry: R0 reason code
                =0 change weights used in colour matching (CTransMiscOp_SetWeights)
                =1 set font colour                        (CTransMiscOp_ReturnPattern)

          IF R0 =CTransMiscOp_SetWeights THEN

            In:   R1 = EOR mask
                  R2 = AND mask      

            Out:  R1 = new value
                  R2 = old value

          IF R0 =CTransMiscOp_ReturnPattern THEN
                
            In:   R1 = physical palette entry
               
            Out:  R1 preserved
                  R2 log2bpp of mode
                  R3 ->pattern block (eight words)

This call is used for functions which do not really deservce a whole SWI of
their own, and are really reserved for internal use only, so to avoid
frightful naughtyness and terrible sordidness they should not be used by
anyone other than people in the know, ie. ourselves.


Service_InvalidateCache
-----------------------

        in: R1=Service_InvalidateCache (&82)
       out: all preserved

This service is broadcast when ever the cache is flushed within ColourTrans.  It
should never be claimed.


ColourTrans_WriteLoadingsToFile
-------------------------------
 
  Entry: R1 file handle

   Exit: -

This code writes a suitable *command to set the error loadings within 
the ColourTrans module.  Upon executing this command it will invalidate
the cache and these values will be used.  This is issued as part of
the desktop-saving sequence.


ColourTrans_SetTextColour
ColourTrans_SetOppTextColour
----------------------------              

        in: R0 =physical colour (&BBGGRRxx)
            R3 =flags word (bit 7 indicates fg/bg colour)
       out: R0 =GCOL value

These call sets the text colour from the specified physical colour.
