
Title; ColourTrans 1.10 (...the choice of a new generation)
Author; David De Vorchik
Created; 3-Feb-93
Status; *** development ***
History;
         3-Feb-93 Diz Created
               

Introduction
------------

This document outlines the changes made between ColourTrans 1.07 (3.1x ROM
release) and the latest versions.

Since the introduction of RISC OS 3.1x several problems have been found
within ColourTrans and its matching of colours and calibration.  This latest
release attempts to over comes these problems and improve the situation with
colour calibration.


Bug fixes:

 * Setting the supremacy bits in the palette no longer corrupts dither
   patterns in non monochrome modes.

 * build_colours functions the core of the colour matching no longer
   use 12 bit masks for 256 colour modes, instead they use a 8 bit mask
   biased towards the Red and Blue components.


Changes:

 * New calibration code


New calibration
---------------

ColourTrans 1.10 and beyond supports the new calibration model as defined by
Ace Computing.  Earlier calibration tables will still work producing the
same results.

To facilitate the new tables the following API changes have been made:

 * *ColourTransMap / *ColourTransMapSize are still suppored, but only
   allow setting of OLD style tables.

 * ColourTrans_WriteCalibrationToFile will only work if an old style
   table is specified.

 * ColourTrans_ConvertDevicePalette is fractionally slower due to recoding
   to use the new algorithms.

 * A new MiscOp has been introduced that allows the caller to read what
   type of table is being used:

        ColourTrans_MiscOp
        ------------------
        in      R0 = 2
        out     R0 = 0 => no calibration table
                     1 => old-style table
                     2 => new-style table
                     other values undefined

 * The calibration is always applied when the colour is being looked up.  So
   when a colour is requested the calibration will be applied and then 
   the colour looked up.  So all calls to read the palette return a non-calibrated
   value.

The format of the new style tables is as follows:

        offset  meaning

        0       Version number (currently must be zero!)
        4       Ideal white expressed as a physical colour (&bbggrrxx)
        8       Ideal black expressed as a physical colour (&bbggrrxx)
        12      SWI number of post processing function
        16      Number of gamma correction tables supplied      
        20...   Base of the gamma tables (256 bytes each)

The first word contains zero, this indicates that it is a new format table. 
If the version field is non-zero then it is assumed that the table is old
format and the old code will be used to process the data.

The following two words contain the ideal black and white values used to
scale the value being calibrated using the following formula:
 
        newR = oldR * (1 - (min(R,G,B) / max (R,G,B)) * (1 - idealR)
        newG = oldG * (1 - (min(R,G,B) / max (R,G,B)) * (1 - idealG)
        newB = oldB * (1 - (min(R,G,B) / max (R,G,B)) * (1 - idealB)

Following the ideal black/white is the SWI number of a post processing
function which is called after the calibration table has been used, this SWI
is called with the same parameters as ColourTrans_ConvertDeviceColour.

After the SWI number follows the gamma information and tables.  There can be
either 1 or 3 tables.  If a single table is present then it is applied to
each of the red, green and blue components of the colour.  Otherwise each
table is used individually on the components.

Each table is assumed to be two hundred and fifty six bytes in length.
