(*
 * Title:  colourtran.h
 * Purpose: C interface to the ColourTrans SWIs
 *
 *)

#ifndef __colourtran_h
#define __colourtran_h

#ifndef __os_h
#include "os.h"
#endif

#ifndef __wimp_h
#include "wimp.h"
#endif

#ifndef __font_h
#include "font.h"
#endif


(* ----------------------- colourtran_select_table -------------------------
 * Description:   Sets up a translation table in a buffer, given a source
 *                mode and palette, and a destination mode and palette.
 *
 * Parameters:    int source_mode -- source mode
 *                wimp_paletteword *source_palette -- source palette
 *                int dest_mode -- destination mode
 *                wimp_paletteword *dest_palette -- destination palette
 *                void *buffer -- pointer to store for the table.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_select_table(source_mode : integer;
                source_palette : wimp_paletteword_ptr;
                dest_mode : integer;
                dest_palette : wimp_paletteword_ptr;
                buffer : pointer) : os_error; extern;


(* ---------------------- colourtran_select_GCOLtable ----------------------
 * Description:   Sets up a list of GCOLs in a buffer, given a source
 *                mode and palette, and a destination mode and palette.
 *
 * Parameters:    int source_mode -- source mode
 *                wimp_paletteword *source_palette -- source palette
 *                int dest_mode -- destination mode
 *                wimp_paletteword *dest_palette -- destination palette
 *                void *buffer -- pointer to store for the list of GCOLs.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_select_GCOLtable(source_mode : integer;
                source_palette : wimp_paletteword_ptr;
                dest_mode : integer;
                dest_palette : wimp_paletteword_ptr;
                buffer : pointer) : os_error; extern;


(* ------------------------- colourtran_returnGCOL -------------------------
 * Description:   Informs caller of the closest GCOL in the current mode
 *                to a given palette entry.
 *
 * Parameters:    wimp_paletteword entry -- the palette entry
 *                int *gcol -- returned GCOL value.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_returnGCOL(entry : wimp_paletteword;
                var gcol : integer) : os_error; extern;


(* ------------------------ colourtran_setGCOL -----------------------------
 * Description:   Informs caller of the closest GCOL in the current mode
 *                to a given palette entry, and also sets the GCOL.
 *
 * Parameters:    wimp_paletteword entry -- the palette entry
 *                int fore_back -- set to 0 for foreground, 
 *                                 set to 128 for background
 *                int gcol_in -- GCOL action
 *                int *gcol_out -- returned closest GCOL.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_setGCOL(entry : wimp_paletteword;
                fore_back : integer;
                gcol_in : integer;
                var gcol_out : integer) : os_error; extern;


(* ---------------------- colourtran_return_colournumber -------------------
 * Description:   Informs caller of the closeset colour number to a given
 *                palette entry, in the current mode and palette
 *
 * Parameters:    wimp_paletteword entry -- the palette entry
 *                int *col -- returned colour number.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_return_colournumber(entry : wimp_paletteword;
                var gcol : integer) : os_error; extern;


(* --------------------- colourtran_return_GCOLformode ---------------------
 * Description:   Informs caller of the closest GCOL to a given palette
 *                entry, destination mode and destination palette.
 *
 * Parameters:    wimp_paletteword entry -- the palette entry
 *                int dest_mode -- destination mode
 *                wimp_paletteword *dest_palette -- destination palette
 *                int *gcol -- returned closest GCOL.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_return_GCOLformode(entry : wimp_paletteword;
                dest_mode : integer;
                dest_palette : wimp_paletteword_ptr;
                var gcol : integer) : os_error; extern;


(* ------------------ colourtran_return_colourformode ----------------------
 * Description:   Informs caller of the closest colour number to a given
 *                palette entry, destination mode and destination palette.
 *
 * Parameters:    wimp_paletteword entry -- the palette entry
 *                int dest_mode -- destination mode
 *                wimp_paletteword *dest_palette -- destination palette
 *                int *col -- returned closest colour number.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_return_colourformode(entry : wimp_paletteword;
                dest_mode : integer;
                dest_palette : wimp_paletteword_ptr;
                var col : integer) : os_error; extern;


(* ----------------------- colourtran_return_OppGCOL -----------------------
 * Description:   Informs caller of the furthest GCOL in the current mode
 *                from a given palette entry.
 *
 * Parameters:    wimp_paletteword entry -- the palette entry
 *                int *gcol -- returned GCOL value.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_return_OppGCOL(entry : wimp_paletteword;
                var gcol : integer) : os_error; extern;


(* ------------------------ colourtran_setOppGCOL --------------------------
 * Description:   Informs caller of the furthest GCOL in the current mode
 *                from a given palette entry, and also sets the GCOL.
 *
 * Parameters:    wimp_paletteword entry -- the palette entry
 *                int fore_back -- set to 0 for foreground,
 *                                 set to 128 for background
 *                int gcol_in -- GCOL action
 *                int *gcol_out -- returned furthest GCOL.
 * Returns:       possible error condition.
 * Other Info:    none. 
 *
 *)
procedure colourtran_setOppGCOL(entry : wimp_paletteword;
                fore_back : integer;
                gcol_in : integer;
                var gcol_out : integer) : os_error; extern;


(* ---------------------- colourtran_return_Oppcolournumber ----------------
 * Description:   Informs caller of the furthest colour number from a given
 *                palette entry, in the current mode and palette
 *
 * Parameters:    wimp_paletteword -- the palette entry
 *                int *col -- returned colour number.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_return_Oppcolournumber(entry : wimp_paletteword;
                var col : integer) : os_error; extern;


(* --------------------- colourtran_return_OppGCOLformode ------------------
 * Description:   Informs caller of the furthest GCOL from a given palette
 *                entry, destination mode and destination palette.
 *
 * Parameters:    wimp_paletteword entry -- the palette entry
 *                int dest_mode -- destination mode
 *                wimp_paletteword *dest_palette -- destination palette
 *                int *gcol -- returned furthest GCOL.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_return_OppGCOLformode(entry : wimp_paletteword;
                dest_mode : integer;
                dest_palette : wimp_paletteword_ptr;
                var gcol : integer) : os_error; extern;


(* ------------------ colourtran_return_Oppcolourformode -------------------
 * Description:   Informs caller of the furthest colour number from a given
 *                palette entry, destination mode and destination palette.
 *
 * Parameters:    wimp_paletteword entry -- the palette entry
 *                int dest_mode -- destination mode
 *                wimp_paletteword *dest_palette -- destination palette
 *                int *col -- returned furthest colour number.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_return_Oppcolourformode(entry : wimp_paletteword;
                dest_mode : integer;
                dest_palette : wimp_paletteword_ptr;
                var col : integer) : os_error; extern;


(* ---------------------- colourtran_GCOL_tocolournumber -------------------
 * Description:   Translates a GCOL to a colournumber (assuming 256-colour
 *                mode).
 *
 * Parameters:    int gcol -- the GCOL
 *                int *col -- returned colour number.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_GCOL_tocolournumber(gcol : integer;
                var col : integer) : os_error; extern;


(* ----------------- colourtran_colournumbertoGCOL -------------------------
 * Description:   Translates a colour number to a GCOL (assuming 256-colour
 *                mode).
 *
 * Parameters:    int col -- the colour number
 *                int *gcol -- the returned GCOL.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_colournumbertoGCOL(col : integer;
                var gcol : integer) : os_error; extern;


(* ------------------ colourtran_returnfontcolours -------------------------
 * Description:   Informs caller of font colours to match given colours.
 *
 * Parameters:    font *handle -- the font's handle
 *                wimp_paletteword *backgnd -- background palette entry
 *                wimp_paletteword *foregnd -- foreground palette entry
 *                int *max_offset
 * Returns:       possible error condition.
 * Other Info:    Closest approximations to fore/background colours will be
 *                set, and as many intermediate colours as possible (up to
 *                a maximum of *max_offset). Values are returned through
 *                the parameters.
 *
 *)
procedure colourtran_returnfontcolours(var handle : font;
                backgnd, foregnd : wimp_paletteword_ptr;
                var max_offset : integer) : os_error; extern;


(* -------------------- colourtran_setfontcolours --------------------------
 * Description:   Informs caller of font colours to match given colours, and
 *                calls font_setfontcolour() to set them.
 *
 * Parameters:    font *handle -- the font's handle
 *                wimp_paletteword *backgnd -- background palette entry
 *                wimp_paletteword *foregnd -- foreground palette entry
 *                int *max_offset
 * Returns:       possible error condition.
 * Other Info:    Closest approximations to fore/background colours will be
 *                set, and as many intermediate colours as possible (up to
 *                a maximum of *max_offset). Values are returned through
 *                the parameters. Font_setfontcolours() is then called with
 *                these as parameters.
 *
 *)
procedure colourtran_setfontcolours(var handle : font;
                backgnd, foregnd : wimp_paletteword_ptr;
                var max_offset : integer) : os_error; extern;


(* ----------------------- colourtran_invalidate_cache ---------------------
 * Description:   To be called when the palette has changed since a call was
 *                last made to a function in this module.
 *
 * Parameters:    void.
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
procedure colourtran_invalidate_cache : os_error; extern;


(* new SWIs *)

(* ----------------------- colourtran_convert_device_colour ----------------
 * Description:   Convert from a device colour to a standard RGB colour
 *
 * Parameters:    wimp_paletteword device colour
                  wimp_paletteword *rgb colour
 * Returns:       possible error condition.
 * Other Info:    Uses the current calibration to convert from a device
 *                colour to a standard RGB palette entry
 *
 *)
procedure colourtran_convert_device_colour(device : wimp_paletteword;
                rgb : wimp_paletteword_ptr) : os_error; extern;

#endif
(* end colourtran.h *)
