Initial revision

[ssr] / StraySrc / Libraries / Steel / h / font

/****************************************************************************
 * This source file was written by Acorn Computers Limited. It is part of   *
 * the RISCOS library for writing applications in C for RISC OS. It may be  *
 * used freely in the creation of programs for Archimedes. It should be     *
 * used with Acorn's C Compiler Release 3 or later.                         *
 *                                                                          *
 ***************************************************************************/

/*
 * 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"

typedef int font; /* 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.
 *
 */

extern os_error * font_cacheaddress(int *version, int *cacheused, int *cachesize);


/* ------------------------------- 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.
 *
 */

extern os_error * font_find(
  char* name,
  int xsize, int ysize,    /* in 16ths of a point */
  int xres, int yres,      /* dots per inch of resolution: 0->use default */
  font*);                  /* result */


/* ------------------------------- 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.
 *
 */

extern os_error * font_lose(font f);

typedef struct font_def {
    char name[16];
    int xsize, ysize, xres, yres; /* as above */
    int usage, age;
} font_def;


/* ------------------------------ 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.
 *
 */

extern os_error * font_readdef(font, font_def*);

typedef struct font_info {
    int minx, miny, maxx, maxy;
} font_info;


/* ------------------------------- 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).
 *
 */

extern os_error * font_readinfo(font, font_info*);


typedef struct font_string {

    char* s;
    int x;                /* inout, in 1/72000 inch */
    int y;                /* inout, in 1/72000 inch */
    int split;            /* inout: space char, or -1 */
                          /* on exit, = count of space or printable */
    int term;             /* inout, index into s */

    } font_string;


/* -------------------------------- 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.
 *
 */

extern os_error * font_strwidth(font_string *fs);


/* paint options */
#define font_JUSTIFY 0x01   /* justify text */
#define font_RUBOUT  0x02   /* rub-out box required */
#define font_ABS     0x04   /* absolute co-ordinates */
        /* 8 not used */
#define font_OSCOORDS 0x10  /* 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.
 *
 */
  
extern os_error * font_paint(char*, int options, int x, int y);


/* ------------------------------- 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.
 *
 */

extern os_error *font_caret(int colour, int height, int flags, int x, int y);


/* ---------------------------- 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.
 *
 */

extern os_error *font_converttoos(int x_inch, int y_inch, int *x_os, int *y_os);


/* --------------------------- 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.
 *
 */

extern os_error *font_converttopoints(int x_os, int y_os, int *x_inch, int *y_inch);


/* ------------------------------- 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.
 *
 */

extern os_error * font_setfont(font);


typedef struct font_state {

       font f;
       int back_colour;
       int fore_colour;
       int offset;

       } font_state;


/* --------------------------------- 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.
 *
 */

extern os_error *font_current(font_state *f);


/* -------------------------------- 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.
 *
 */

extern os_error *font_future(font_state *f);


/* ------------------------------- 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.
 *
 */

extern os_error *font_findcaret(font_string *fs);


/* ----------------------------- 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.
 *
 */

extern os_error * font_charbbox(font, char, int options, font_info*);


/* -------------------------- 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.
 *
 */

extern os_error *font_readscalefactor(int *x, int *y);


/* ---------------------------- 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.
 *
 */

extern os_error *font_setscalefactor(int x, int y);


/* ------------------------------- 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.
 *
 */

extern os_error * font_list(char*, int*);

                 
/* ------------------------------ 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.
 *
 */

extern os_error * font_setcolour(font, int background, int foreground, int offset);


#define font_BlueGun  0x01000000 /* 8-bit field: phsical colour blue gun.  */
#define font_GreenGun 0x00010000 /* 8-bit field: phsical colour green gun. */
#define font_RedGun   0x00000100 /* 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).
 *
 */

extern os_error *font_setpalette(int background, int foreground, int offset, 
                          int physical_back, int physical_fore);

typedef struct font_threshold {

     char offset;
     char thresholds[15];

     } font_threshold;
                                        

/* ------------------------- 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.
 *
 */

extern os_error *font_readthresholds(font_threshold *th);


/* ------------------------- 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.
 *
 */

extern os_error *font_setthresholds(font_threshold *th);


/* ------------------------- 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.
 *
 */

extern os_error *font_findcaretj(font_string *fs, int offset_x, int offset_y);


/* ------------------------ 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.
 *
 */
   
extern os_error *font_stringbbox(char *s, font_info *fi);

/* new SWIS */

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

typedef enum {font_CONVERT, font_IGNORE, font_ERROR} font_action_on_bitmap;

extern os_error
   *font_output_to_null
   (  BOOL add_hints,
      BOOL output_skeleton,
      font_action_on_bitmap action_on_bitmap
   );

extern os_error *font_output_size (size_t *size);

extern os_error
   *font_output_to_buffer
   (  drawmod_buffer *buff_ptr,
      BOOL add_hints,
      BOOL output_skeleton,
      font_action_on_bitmap action_on_bitmap
   );

extern os_error *font_output_to_screen (void);

# endif

/* end font.h */