ColourTrans Extensions in RiscOS 3.10

ColourTrans_SelectTable

        in:  r0  = source mode
                      =  -1 for current
                      < 256 for specified mode
                     >= 256 for -> sprite area
                
             r1  = source palette
                     if r0 >=256 then;
                        if r5,bit 0 clear -> sprite name
                        if r5,bit 0 set -> sprite in block
                     if r0 < 256 then;
                        r1 =-1 use current
                           = 0 use default for mode
                           > 0 use palette table at r1
             r2,r3,r4 as before.
          
             if r0 >=256 then:
                        r5 = flags word
                                bit 0 set -> r1 -> sprite not name
                                bit 1 set -> use current palette not default 
                                             if sprite doesn't have one
                                other bits reserved - should be zero
        out: as before
        
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.

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 capable 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 intercepting 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
         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.

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 deserve 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.