WimpExtension document: FastChars Library (&1F)                       Doc 06
============================================================================

The FastChars library provides calls for writing text to the screen. Its
purpose is that it will usually use direct screen access, which is
considerably faster than using standard OS calls. In situations for which
there is no direct screen access routine, it will default to using the
OS calls.

The library also provides a useful extension to the ordinary OS_WriteC
routines in that it can do certain 'special effects' with the text - namely
bold, italic, faint and underline.

Note that the FastChars routines are not 'masked' - i.e. the pixels in the
character which are not 'lit' will be set to the specified background
colour, rather than not plotted, as is usual with VDU 5 OS calls.

Note: This routine may not work correctly if the user has a non-standard
graphics card. In this situation they can define the System variable:
  WimpExt$FastChars_UseOS
and the FastChars library will then ONLY use the OS calls (which should
always work).


R0 = &00 : Set-up font
----------------------
R1-> font data (0 to use system font)
If R1<>0:
R2-> high-resolution font data (0 to use low-resolution font scaled)
R3 = character width in pixels (currently MUST BE 8)
R4 = character height in pixels (of the low-resolution font) (1-32)
R5 = horizontal spacing in pixels

Sets up the font data to be use by the plotting commands. Note that
currently the character width must be 8 pixels. You can optionally provide
a high-resolution font for use in high-resolution screen modes - this must
be double the height of the low-resolution font. If no high-resolution font
is provided then the low-resolution font will be automatically scaled and
used in high-resolution screen modes.

R0 = &01 : Set foreground colour
--------------------------------
R2 = foreground colour (as for writing directly to screen memory)

R0 = &02 : Set background colour
--------------------------------
R2 = background colour (as for writing directly to screen memory)

R0 = &03 : Set attributes
-------------------------
R2 = EOR word
R3 = clear word

The new attributes flags are calculated by:
  new_attr = (old_attr AND NOT clear_word) EOR eor_word

The attributes flags have the following meanings:
  bit   meaning if set
  0     bold
  1     italic
  2     underline
  3     faint
  4     double-height
  5     position in character for double-height text (0=top, 1=bottom)
  6     double-width
  7     position in character for double-width text (0=left, 1=right)
  8-31  undefined; MUST BE 0

Note that it is not sensible to have text which is both bold *and* faint.

R0 = &04 : Set cursor position
------------------------------
R2 = XPos (OS units)
R3 = YPos (OS units)

R0 = &05 : Set clipping window
------------------------------
R2 = XMin (OS units)
R3 = YMin (OS units)
R4 = XMax (OS units)
R5 = YMax (OS units)

All co-ordinates are inclusive. No plotting will be performed outside the
clipping window.

R0 = &06 : Write character
--------------------------
R2 = character byte

Writes the character using the current cursor position, foreground and
background colours, and attributes. The cursor X position is incremented by
the horizontal spacing as set up by call R0=&00 (see above).

R0 = &07 : Write control-terminated string
------------------------------------------
R2-> control-terminated string

Displays the specified string as if by using repeat calls R0=&06 (see
above).

R0 = &08 : Write string with length
-----------------------------------
R2-> string
R3 = length of string

Displays the specified string as if by using repeat calls R0=&06 (see
above).

R0 = &09 : Read address of plot routine
---------------------------------------
Exit:
R0-> plot routine

Reads the address of the plot routine, for fast access. The routine must be
entered in SVC mode as follows:
  R0  = character byte
  R1  = foreground colour
  R2  = background colour
  R3  = attributes flags
  R4  = XPos (OS units)
  R5  = YPos (OS units)
  R13-> supervisor stack
  R14-> return address
