> net#arf:$.a500.RiscOS+.doc.Colours

 Description: Documentation of changes to ColourTrans
 Author:  Gavin Stark, David De Vorchik
 Status:  Definitive ?
 History:
    01-10-89  GStark  Created document. Specification for Colour calibration
    27-10-89  GStark  Inserted bad news about ECF's in ColourTrans
    17-11-91  DDV     Added stuff about CMYK and HSV conversions.

ColourTrans and Colour Calibration
---------------------------

The new versions of ColourTrans include major new features:

(*) ECF setting for SetGCOL to give a wider range of colours than
        the true colours available on the screen
(*) Colour calibration to allow screen and printer to produce the
        same colours.
                                   
The ECF setting in SetGCOL is only used when bit 8 of R3 is set. This
makes the parameters for the call as follows:

  ColourTrans_SetGCOL (SWI &40743)
On entry:
        R0 = palette entry (&BBGGRR00)
        R3 bit 7 set   => set background colour
           bit 7 clear => set foreground colour
           bit 8 set   => use ECF's to give a better approximation to the colour
           bit 8 clear => don't use ECF's
        R4 = GCOL action
On exit:
        R0 = GCOL number (as returned by ReturnGCOL - even ig using an ECF)
        R2 = Log2 of bits-per-pixel for the current screen mode
        R3 = original R3 ANDed with &80
        R4 preserved
                          
Colour Calibration - what it means
----------------------------------

There is a major problem at the moment in working with
colour documents. This is that, if the user selects
some colours on the screen, they may well come out as
different colours on the printer or other final output
device. Colour calibration is a way to get round this
problem.

The colour calibration involves calibrating the
screen colours with a fixed standard set of colours, and
also calibrating the output device colours to the same
fixed set of colours. Then, when applications draw on the
screen, they do so in standard colours which are converted
by the OS to screen colours. If the application draws to the
printer it will again do so in standard colours, but this
converting it to printer colours.

So, for the user, calibrating the colours will give constant
colour reproduction throughout the system, for the cost of
calibrating the devices in the first place.

For the OS it means providing some method of converting from
standard colours to device colours. This is done using the
ColourTrans module.


Method of operation
-------------------

The calibration aspect of ColourTrans will be performed using
a function map from device to standard colour (a one-to-one map,
but not necessarily filling the standard colour space). To
evaluate the function of a specific device colour, ColourTrans
will split the device colour into three component parts (Red,
Green and Blue on a monitor, for example). Then, for each component,
it will use linear interpolation between the two device components
'surrounding' the required device component. The standard colours
thus obtained for each component will then be summed to give
the final calibrated colour. This implies the calibration map will
be a set of (device,standard) component/colour pairs which
completely cover the device component range. The default calibration
for the screen will be:
                         BBGGRR                              BBGGRR
  Red = 00 -> Standard = 000000       Red = FF -> Standard = 0000FF
Green = 00 -> Standard = 000000     Green = FF -> Standard = 00FF00
 Blue = 00 -> Standard = 000000      Blue = FF -> Standard = FF0000

This mapping produces the same effect as the uncalibrated versions
of ColourTrans provide for the screen.


Current interfaces to ColourTrams
---------------------------------
At the moment ColourTrans provides the following SWI's:
  SelectTable
        provide a colour translation table for sprites
  SelectGCOLTable
        provide a table of GCOLs for conversion between modes
‰ ReturnGCOL
        return screen GCOL corresponding to standard colour
‰ SetGCOL
        set ECF corresponding to standard colour
‰ ReturnColourNumber
        return screen colour corresponding to standard colour
‰ ReturnGCOLForMode
        return screen GCOL corresponding to standard colour
‰ ReturnColourNumberFor Mode
        return screen colour corresponding to standard colour
‰ ReturnOppGCOL
        return GCOL furthest from standard colour
‰ SetOppGCOL
        set GCOL furthest from standard colour
‰ ReturnOppColourNumber
        return colour furthest from standard colour
‰ ReturnOppGCOLForMode
        return GCOL furthest from standard colour
‰ ReturnOppColourNumberForMode
        return colour furthest from standard colour
  GCOLToColourNumber
        convert a GCOL to a screen colour number
  ColourNumberToGCOL
        convert a screen colour to a GCOL colour
‰ ReturnFontColours
        return range of colours between two standard colours
‰ SetFontColours
        set a range of colours between two standard colours
  InvalidateCache
        invalidate the palette cache

The SWI's marked ‰ are those which will be affected by the changes
I envisage for ColourTrans.


Calibration tables
------------------

The calibration table will be of the following form:

  For three device components i (be they Red/Green/Blue or CMY)
    For a range of n(i) percentages
       Percentage p of device component i corresponds to the standard colour
       RGB(p,i).

     Word       Meaning
       0         Number of pairs of component 1 ( >= 2 )
       1         Number of pairs of component 2 ( >= 2 )
       2         Number of pairs of component 3 ( >= 2 )
      3-2+n(1)   Pairs for component 1
      ...        Pairs for component 2
      ...        Pairs for component 3

The pairs will be stored as 32-bit words, in the form &BBGGRRDD, where DD
is the device 'percentage', i.e. value of the device component from 0 to 255.
BBGGRR is the standard colour corresponding to that devie component percentage.

The length of the table will be 3 + n(1) + n(2) + n(3) words.


Proposed SWI's
--------------

        SWI ColourTrans_SetCalibration
        In:     R0 -> Calibration table
        Out:

The calibration table pointed to by R0 is copied into the RMA as the new
calibration table for the screen. If the call fails due to lack of room
in the RMA then the calibration will be set to the default calibration for
the screen, and the 'No room in RMA' error will be passed back. Another
possible error is 'Bad calibration table', given if the device component
pairs do not cover the full range 00 to &FF.


        SWI ColourTrans_ReadCalibration
        In:  Either   R0 = 0 to read table size
                or    R0 -> Address to copy calibration table to
        Out: Either   R1 = table size
                or   [R0] updated

The table pointed to by R0 should be large enough to contain the complete
table. Ideally this call should be issued first with R0=0 to read the size
of the table, then space allocated, and then the table can be read.
           

        SWI ColourTrans_ConvertDeviceColour
        In:     R1 = 24-bit device colour (&BBGGRR00 for the screen)
                R3 = 0 for the current screen calibration
             or R3 -> calibration table to be used
        Out:    R2 = 24-bit standard colour (&BBGGRR00)

This call allows applications to read, say, screen colours, and find the
standard colours to which they correspond. The colour selector in
RISCOSlib should use this call.


        SWI ColourTrans_ConvertDevicePalette
        In:     R0 = number of colours to convert
                R1 -> table of 24-bit device colours
                R2 -> table to store standard colours
                R3 = 0 for current screen calibration
             or R3 -> calibration table to use
        Out:   [R2] updated.

This call allows printer drivers to use the same calibration calculation
code for their conversions between device and standard colours as the
screen does. The printer device palette can be set up and then converted
using this call to the standard colours using the printers calibration
table. This call is mainly provided to ease the load on the writers of
printer drivers.
                

        SWI ColourTrans_ConvertRGBToCIE
           In:  R0,R1,R2: RGB colour
           Out: R0,R1,R2: CIE XYZ tristimulus values
        SWI ColourTrans_ConvertCIEToRGB
           In:  R0,R1,R2: CIE XYZ tristimulus values
           Out: R0,R1,R2: RGB colour

The problem with defining our own standard set of RGB colours is that
nobody else uses them. This is fine for the internals of ColourTrans,
but when it comes to interfacing with the real world it would be nice
to interface to a standard colour space system. CIE is a standard
method for defining colours, and these calls could be implemented to
allow interaction with the real world using CIE colours. The CIE
standard chosen is the XYZ tristimulus values.

The values should be fixed point, with 16 bits below the point and
16 bits above the point. R0 will be the red component or the X tristimulus
value. R1 will be the green component or the Y tristimulus value. R2 will
be the blue componet or the Z tristimulus value, as appropriate.


        SWI ColourTrans_WriteCalibrationToFile             
        In:  R0 = flags
             R1 = file handle of file to save calibration to
        Out: R0 corrupted

This SWI is used to save the current calibration to a file. The
calibration is saved by creating a list of * commands which will
recreate the current calibration.

If R0 bit 0 is clear then the calibration will only be saved if it
is not the default calibration. If R0 bit 0 is set then the
calibration will be saved even if it is the default calibration.


        SWI ColourTrans_ConvertRGBToHSV
        In:  R0, R1, R2: RGB values
        Out: R0, R1, R2: HSV values
                                   
        SWI ColourTrans_ConvertHSVToRGB
        In:  R0, R1, R2: HSV values
        Out: R0, R1, R2: RGB values

This SWI converts the given Red, Green and Blue into the correct Hue,
Saturation and Value. 

Each quantity is specified as a 16.16 unsigned fixed point value, Hue ranges
from 0->360 with no fractional element, Saturation and Value are specified
from 0->1.0.
             
When dealing with achromatic colours hue will be undefined. An error will be
generated when the HSV to RGB SWI is called and a hue value is defined when
the other values indicate that the colour as achromatic.


        SWI ColourTrans_ConvertRGBToCMYK
        In:  R0, R1, R2: RGB values
        Out: R0, R1, R2, R3: CMYK values

        SWI ColourTrans_ConvertCMYKToRGB
        In:  R0, R1, R2, R3: CMYK values
        Out: R0, R1, R2: RGB values

This converts from the RGB colour model into the CMY model with a K
(key/black) additive.  This is a commonly used colour model when performing
colour seperatations.

'C' is used to indicate how much cyan is within the colour, 'M' for magenta
and 'Y' for yellow.  The 'K' acts as a black additive and is a value equally
subtracted or added to the given CMY values.

All values are 16.16b quantities ranging from 0->1.


Calibrating devices - !ColourCal
--------------------------------

This application will allow a device to be calibrated.

The user interface will be:
        A set of colour blocks (n brightnesses of colours 1,2,3 and all
                three combined, and a single block with no colours)
        Writeable icons next to the blocks, which the user fills in after
                matching the block with a set of printed blocks on a
                matching card. Each of the printed blocks will have its
                its standard RGB value printed next to it.

The user's monitor should ideally be set at full contrast, and a brightness
level just below that where the black of the monitor starts to glow grey.
This should give the largest range of colours available.

                                                        
Saving the calibration                                  
----------------------

The screen calibration mapping must be saved when the current desktop state is
saved by the Task Manager module, and in order to do this there needs to be
*commands that perform the equivalent of the SetCalibration SWI above.  Suitable
*commands would be:
                                   
        *ColourTransMapSize <n(1)> <n(2)> <n(3)>
        *ColourTransMap RRGGBBDD RRGGBBDD RRGGBBDD RRGGBBDD etc.
                             
n(1) is the number of device 'percentages' for device component 1.
n(2) is the number of device 'percentages' for device component 2.
n(3) is the number of device 'percentages' for device component 3.

'RRGGBBDD' denotes 8 hex digits, such that &RRGGBBDD is the
appropriate true colour setting for the device component

When "Save desktop" is selected on the Task Manager menu, it is possible
that the !ColourCal application will no longer be loaded.  Therefore the
Task Manager module itself would find out the current translations from the
ColourTrans module, and generate the *commands, which are inserted in the
desktop startup file.

!ColourCal would also allow the calibration setup to be saved in an obey
file, so that the calibration setup is not necessarily tied in to the
desktop state.




D.Seal comments:

If a test card contains saturated colours,
people may have a lot of trouble finding even a reasonably close
approximation to them. On the other hand, if it doesn't, we will be missing
information required to interpolate part of the colour space...

If saturation differences are
important in a picture, it may turn out to be better to represent the
unsaturated RGB colour by an unsaturated screen colour, accepting a less
good absolute match on that colour in order to preserve differential colour
information.

