(*
 * Title  : font.h
 * Purpose: access to RISC OS font facilities
 *
 *)

# ifndef __font_h
# define __font_h

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

# include "drawmod.h"

type font_ptr = ^font;
     font = integer;    (* abstract font handle *)


(* ---------------------------- font_cacheaddress --------------------------
 * Description:   Informs caller of font cache used and font cache size.
 *
 * Parameters:    int *version -- version number
 *                int *cacheused -- amount of font cache used (in bytes)
 *                int *cachesize -- total size of font cache (in bytes)
 * Returns:       os_error* -- possible error condition
 * Other Info:    Version number is *100, so v.1.07 would be returned as 107.
 *
 *)
function font_cacheaddress(var version : integer;
                var cacheused : integer;
                var cachesize : integer) : os_error; extern;


(* ------------------------------- font_find -------------------------------
 * Description:   Gives caller a handle to font, given its name.
 *
 * Parameters:    char *name -- the font name
 *                int xsize, ysize -- x/y point size (in 16ths of a point)
 *                int xres, yres -- x/y resolution in dots per inch
 *                font* -- the returned font handle
 * Returns:       Possible error condition.
 * Other Info:    none.
 *
 *)
function font_find(name : string;
                xsize, ysize : integer;    (* in 16ths of a point *)
                xres, yres : integer;      (* dots per inch of resolution: *)
                                           (* 0->use default *)
                var result : font) : os_error; extern;


(* ------------------------------- font_lose -------------------------------
 * Description:   Informs font manager that a font is no longer needed
 *
 * Parameters:    font f -- the font
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_lose(f : font) : os_error; extern;

type font_def_ptr = ^font_def;
     font_def =
       record
         name : packed array[1..15] of char;
         xsize, ysize, xres, yres : integer;  (* as above *)
         usage, age : integer
       end;


(* ------------------------------ font_readdef -----------------------------
 * Description:   Get details about a font, given its handle.
 * 
 * Parameters:    font -- the font handle
 *                font_def* -- pointer to buffer to hold returned details
 * Returns:       possible error condition.
 * Other Info:    This function fills in details re: font, into the supplied
 *                buffer(a variable of type 'font_def').
 *                fields of this buffer are as follows:
 *                          name -- font name
 *                          xsize, ysize -- x/y point size * 16
 *                          xres, yres -- x/y resolution (dots per inch)
 *                          usage -- number of times Font_FindFont has found
 *                                   the font minus number of times 
 *                                   Font_LoseFont has been used on it
 *                          age -- number of font accesses made since this
 *                                 one was last accessed.
 *
 *)
function font_readdef(f : font;
                result : font_def_ptr) : os_error; extern;

type font_info_ptr = ^font_info;
     font_info =
       record
         minx, miny, maxx, maxy : integer
       end;


(* ------------------------------- font_readinfo ---------------------------
 * Description:   Informs caller of minimal area covering any character in
 *                the font bounding box.
 *
 * Parameters:    font -- the font handle
 *                font_info* -- pointer to buffer to hold returned details
 * Returns:       possible error condition.
 * Other Info:    Fills in details re: font in supplied buffer (variable of
 *                type 'font_info').
 *                fields of this buffer are as follows:
 *                       minx -- min x coord in pixels (inclusive)
 *                       maxx -- max x coord in pixels (inclusive)
 *                       miny -- min y coord in pixels (exclusive)
 *                       maxy -- max y coord in pixels (exclusive).
 *
 *)
function font_readinfo(f : font;
                result : font_info_ptr) : os_error; extern;


type font_string_ptr = ^font_string;
     font_string =
       record
         s : string;
         x : integer;          (* inout, in 1/72000 inch *)
         y : integer;          (* inout, in 1/72000 inch *)
         split : integer;      (* inout: space char, or -1 *)
                               (* on exit, = count of space or printable *)
         term : integer        (* inout, index into s *)
       end;


(* -------------------------------- font_strwidth --------------------------
 * Description:   Determine 'width' of string.
 *
 * Parameters:    font_string *fs -- the string, with fields:
 *                              s -- string itself
 *                              x -- max x offset before termination
 *                              y -- max y offset before termination
 *                          split -- string split character
 *                           term -- index of char to terminate by
 * Returns:       possible error condition.
 * Other Info:    On exit fs fields hold:
 *                              s -- unchanged
 *                              x -- x offset after printing string
 *                              y -- y offset after printing string
 *                          split -- no. of split chars found
 *                                   no. of printable chars if split was -1
 *                           term -- index into string at which terminated.
 *
 *)
function font_strwidth(fs : font_string_ptr) : os_error; extern;


(* paint options *)
const   font_JUSTIFY  = $01;  (* justify text *)
        font_RUBOUT   = $02;  (* rub-out box required *)
        font_ABS      = $04;  (* absolute co-ordinates *)
        (* 8 not used *)
        font_OSCOORDS = $10;  (* os coords supplied otherwise 1/72000 inch *)


(* ------------------------------- font_paint -----------------------------
 * Description:   Paint the given string at coords x,y.
 * 
 * Parameters:    char * -- the string
 *                int options -- set using "paint options" defined above
 *                int x, y -- coords (either os or 1/72000 inch)
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_paint(s : string;
                options : integer;
                x, y : integer) : os_error; extern;


(* ------------------------------- font_caret -----------------------------
 * Description:   Set colour, size and position of the caret.
 *
 * Parameters:    int colour -- EORed onto screen
 *                int height -- in OS coordinates
 *                int flags -- bit 4 set ==> OS coords, else 1/72000 inch
 *                int x,y   -- x/y coords
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_caret(colour : integer;
                height : integer;
                flags : integer;
                x, y : integer) : os_error; extern;


(* ---------------------------- font_converttoos ---------------------------
 * Description:   Converts coords in 1/72000 inch to OS units.
 *
 * Parameters:    int x_inch, y_inch -- x/y coords in 1/72000 inch
 *                int *x_os, *y_os -- x/y coords in OS units
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_converttoos(x_inch, y_inch : integer;
                var x_os, y_os : integer) : os_error; extern;


(* --------------------------- font_converttopoints ------------------------
 * Description:   Converts OS units to 1/72000 inch.
 *
 * Parameters:    int x_os, y_os -- x/y coords in OS units
 *                int *x_inch, *y_inch -- x/y coords in 1/72000 inch
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_converttopoints(x_os, y_os : integer;
                var x_inch, y_inch : integer) : os_error; extern;


(* ------------------------------- font_setfont ----------------------------
 * Description:   Sets up font used for subsequent painting or size-requests.
 *
 * Parameters:    font -- the font handle
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_setfont(f : font) : os_error; extern;


type font_state_ptr = ^font_state;
     font_state =
       record
         f : font;
         back_colour : integer;
         fore_colour : integer;
         offset : integer
       end;


(* --------------------------------- font_current --------------------------
 * Description:   Informs caller of current font state.
 *
 * Parameters:    font_state *f -- pointer to buffer to hold font state
 * Returns:       possible error condition.
 * Other Info:    returned buffer(into variable of type 'font_state'):
 *                         font f -- handle of current font
 *                         int back_colour -- current background colour
 *                         int fore_colour -- current foreground colour
 *                         int offset -- foreground colour offset.
 *
 *)
function font_current(f : font_state_ptr) : os_error; extern;


(* -------------------------------- font_future ----------------------------
 * Description:   Informs caller of font characteristics after a future
 *                font_paint.
 *
 * Parameters:    font_state *f -- pointer to buffer to hold font state
 * Returns:       possible error condition.
 * Other Info:    buffer contents:
 *                          font f -- handle of font which would be selected
 *                          int back_colour -- future background colour
 *                          int fore_colour -- future foreground colour
 *                          int offset -- foreground colour offset.
 *
 *)
function font_future(f : font_state_ptr) : os_error; extern;


(* ------------------------------- font_findcaret --------------------------
 * Description:   Informs caller of nearest point in a string to the caret
 *                position.
 *
 * Parameters:    font_string *fs -- the string
 *                         fields:  char *s -- the string itself
 *                                  int x,y -- x/y coords of caret
 * Returns:       possible error condition.
 * Other Info:    returned fields of fs as in font_strwidth.
 *
 *)
function font_findcaret(fs : font_string_ptr) : os_error; extern;


(* ----------------------------- font_charbbox -----------------------------
 * Description:   Informs caller of bounding box of char in given font.
 *
 * Parameters:    font -- the font handle
 *                char -- the ASCII character
 *                int options -- only relevant option if font_OSCOORDS
 *                font_info * -- pointer to buffer to hold font info
 * Returns:       possible error condition.
 * Other Info:    if OS coords are used and font has been scaled, box may
 *                be surrounded by area of blank pixels.
 *
 *)
function font_charbbox(f : font;
                c : char;
                options : integer;
                result : font_info_ptr) : os_error; extern;


(* -------------------------- font_readscalefactor -------------------------
 * Description:   Informs caller of x and y scale factors used by font.
 *                manager for converting between OS coords and 1/72000 inch
 *
 * Parameters:    int *x, *y -- returned scale factors
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_readscalefactor(var x, y : integer) : os_error; extern;


(* ---------------------------- font_setscalefactor -----------------------
 * Description:   Sets the scale factors used by font manager.
 *
 * Parameters:    int x,y -- the new scale factors
 * Returns:       possible error condition.
 * Other Info:    scale factors may have been changed by another application
 *                well-behaved applications save and restore scale factors.
 *
 *)
function font_setscalefactor(x, y : integer) : os_error; extern;


(* ------------------------------- font_list -------------------------------
 * Description:   Gives name of an available font.
 *
 * Parameters:    char* -- pointer to buffer to hold font name
 *                int*  -- count of fonts found (0 on first call)
 * Returns:       possible error condition.
 * Other Info:    count is -1 if no more names
 *                typically used in loop until count == -1.
 *
 *)
function font_list(s : string; var n : integer) : os_error; extern;

                 
(* ------------------------------ font_setcolour ---------------------------
 * Description:   Sets the current font(optionally), changes foreground
 *                and background colours, and offset for that font.
 * 
 * Parameters:    font -- the font handle (0 for current font)
 *                int background, foreground -- back/foreground colours
 *                int offset -- foreground offset colour (-14 to +14) 
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_setcolour(f : font;
                background, foreground : integer;
                offset : integer) : os_error; extern;


const font_BlueGun  = $01000000; (* 8-bit field: phsical colour blue gun.  *)
      font_GreenGun = $00010000; (* 8-bit field: phsical colour green gun. *)
      font_RedGun   = $00000100; (* 8-bit field: phsical colour red gun.   *)


(* --------------------------- font_setpalette -----------------------------
 * Description:   Sets the anti-alias palette
 *
 * Parameters:    int background -- logical background colour
 *                int foreground -- logical foreground colour
 *                int offset -- foreground colour offset
 *                int physical_back -- physical background colour
 *                int physical_fore -- physical foreground colour
 * Returns:       possible error condition.
 * Other Info:    physical_back and physical_fore are of the form:
 *                        0xBBGGRR00 (see #defines above).
 *
 *)
function font_setpalette(background, foreground : integer;
                offset : integer;
                physical_back : integer;
                physical_fore : integer) : os_error; extern;

type font_threshold_ptr = ^font_threshold;
     font_threshold =
       record
         offset : byte;
         thresholds : array[0..14] of byte
       end;
                                        

(* ------------------------- font_readthresholds ---------------------------
 * Description:   Reads the list of threshold values that the font manager
 *                uses when painting characters.
 *
 * Parameters:    font_theshold *th -- pointer to result buffer
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_readthresholds(th : font_threshold_ptr) : os_error; extern;


(* ------------------------- font_setthresholds ----------------------------
 * Description:   Sets up threshold values for painting colours.
 *
 * Parameters:    font_threshold *th -- pointer to a threshold table
 * Returns:       possible error condition.
 * Other Info:    none.
 *
 *)
function font_setthresholds(th : font_threshold_ptr) : os_error; extern;


(* ------------------------- font_findcaretj -------------------------------
 * Description:   Finds nearest point where the caret can go (using
 *                justification offsets).
 *
 * Parameters:    font_string *fs -- the string (set up as in font_findcaret)
 *                int offset_x, offset-y -- the justification offsets
 * Returns:       possible error condition.
 * Other Info:    if offsets are both zero then same as font_findcaret.
 *
 *)
function font_findcaretj(fs : font_string_ptr;
                offset_x, offset_y : integer) : os_error; extern;


(* ------------------------ font_stringbbox --------------------------------
 * Description:   Measures the size of a string (without printing it).
 *
 * Parameters:    char *s -- the string
 *                font_info *fi -- pointer to buffer to hold font info
 * Returns:       possible error condition.
 * Other Info:    fields returned in fi are:
 *                    minx, miny -- bounding box min x/y
 *                    maxx, maxy -- bounding box min x/y.
 *
 *)
function font_stringbbox(s : string;
                fi : font_info_ptr) : os_error; extern;

(* new SWIS *)

(*---------------------------------------------------------------------------*)
(*Routines to create a draw module path object from calls to font_paint*)

const font_CONVERT = 0;
      font_IGNORE = 1;
      font_ERROR = 2;

type font_action_on_bitmap_ptr = ^font_action_on_bitmap;
     font_action_on_bitmap = integer;

function font_output_to_null(add_hints : boolean;
           output_skeleton : boolean;
           action_on_bitmap : font_action_on_bitmap) : os_error; extern;

function font_output_size(var size : integer) : os_error; extern;

function font_output_to_buffer(buff_ptr : drawmod_buffer_ptr;
           add_hints : boolean;
           output_skeleton : boolean;
           action_on_bitmap : font_action_on_bitmap) : os_error; extern;

function font_output_to_screen : os_error; extern;

# endif

(* end font.h *)
