
Work to do on Font Manager
-------------------------

RAM-scaled fonts
    ensure 4-bpp bitmap used as the source

SWI Font_FindFontTransformed
    R1 -> font name
    R2,R3 = font size
    R4,R5 = dpi
    R6 -> matrix (0 => unit matrix)
        6 words, cf. Draw module matrix
        First 4 words dimensionless, 1 == 1<<16
        Next 2 are the displacement, in 1/1000 of the point size
    R7 = line width: -1 => filled, 0 => thin, else line width in 1/1000th em
        if R7 >= 0, the character outlines are stroked (and skeleton lines ignored)
        if R7 = -1, the character outlines are filled
        in both cases the colour used is the font foreground colour

    separate scaling due to font size / device resolution
    modify scaffolding according to the matrix
        for 90 degree rotations/reflections, the scaffolding can still be used
        otherwise it must be ignored
    watch out for backward fonts:
        if direction < 0, check limits in opposite manner in Font_ScanString
        Font_StringWidth must continue to get it wrong

SWI extra info on font metrics (cf: OS_ReadVduVariables)
    italic angle
    fixed pitch?
    underline posn / thickness
    CapHeight
    XHeight
    Descender
    Ascender
    kerning
    ligatures

SWI Font_CharBBox:
€   for subpixel fonts, return the union of all boxes

---- related grid lines (mostly done):
----    linearly-dependent lines (eg. middle scaffold line of a 'B')

SWI Font_PaintString:
    R0 = initial font handle (0 => use previous one, as for Font_Paint)
    R1 -> string
    R2 = flags
        bit 0 => supply justification offset for spaces in R7!0..R7!4
        bit 1 => supply rubout box in R7!8..R7!20
        bit 2 => supply justification offset for all chars in R7!24..R7!28 - including spaces
        bit 3 => perform kerning as defined in the font metrics
        bit 4 must be 0 (use 1/72000th inch for all coords)
        bit 5 => perform ligaturing as defined in the font metrics
        bits 6,7 must be 0
    R3,R4 = start coords (1/72000th inch)
    R5 = index of char to stop by (eg. if R5=4, print only 4 chars)
    R6 -> block defining the colours/underlining (0 => use current colours, as for Font_Paint)
        R6!0 = background colour
        R6!4 = first foreground colour
        R6!8 = font colour offset (0=>monochrome)
        R6!12 = initial underline position (1/72000")
        R6!16 = initial underline thickness (1/72000") - 0 => no underlining
        R6!20 = split char (for Font_ScanString)
    R7 -> block containing extra coords (0 => none)
        R7!0..R7!4 = increment on spaces (if R2 bit 0 set)
        R7!8..R7!20 = rubout box coords (if R2 bit 1 set) - includes both corners
        R7!24..R7!28 = increment on all chars (if R2 bit 2 set) - including spaces
        R7!32..R7!36 = coords to stop scanning by (for Font_ScanString)

The values of underline position/height supplied in the middle of a string
can be converted to 1/72000" by multiplying by the point size of the font
and dividing by 256 (note that the underline position is a 7-bit number in
bits 0..6 and a sign bit in bit 7, whereas the underline height is an
unsigned 8-bit number).  Note also that if the font is transformed, the
underlining is also transformed in the direction of the font's baseline.
This is done by the font manager noting that the y-offset after the
character was non-zero.

SWI Font_ScanString:
       All parameters as for Font_PaintString, except for:
       R2 bit 1 set => return bounding box of string (bit 4 => 1/72000" or OS units)
       R2 bit 4 set => return bounding box in OS units - this is guaranteed to cover the pixels
       R2 bit 6 set => return the nearest caret position (cf. Font_FindCaretJ)
       R7!32..R7!36 = coords to stop by (cf. R2,R3 in Font_StringWidth)
          If x=R7!32 or y=R7!36 are less than R3 or R4, the scan will only
          stop when the cursor has moved to LESS than x or y - set
          x/y=max(R3/R4,x/y) if you don't want this (eg. when doing a
          Font_FindCaret).  The feature is designed to allow formatting of
          text which is transformed. Normally such text will be formatted
          inside a parallelogram, one of whose sides is in the direction of
          the transformed baseline of the font, and the other is at 90
          degrees to it.  Depending on the direction of the baseline, x
          and/or y may be less than R3 or R4.

       As for Font_StringWidth, Font_FutureFont can be used to test the
       result of painting the string.

SWI Font_ReadFontDefn:      (cf. Font_ReadDefn)
In    R0 = font handle
       R1 -> buffer to hold font name (max 40 chars)
       R6 -> buffer to hold matrix (6 words) - cf. Font_FindFontTransformed
Out  R1 -> updated font name buffer
       R2,R3 = font size
       R4,R5 = dpi
       R6 -> matrix (R6=0 => unit matrix, and buffer contains a unit matrix)
       R7 = line width: -1 => filled, 0 => thin, else line width in 1/1000th em

SWI Font_SwitchOutputToBuffer
In  R0 -> buffer (0 => back to normal, -1 => leave it alone, ie. just read setting)
    R0!0 = 0
    R0!4 = space remaining in buffer (from R0+8 onwards)
Out R0 -> old buffer address (ie. the end of the buffer) (0 => output was to screen)
    if R0<>0, R0!0 = error status for buffer
       (to report error, set V and let R0=R0!0)

Subsequent calls to Font_Paint will cause the outline definitions of the
painted strings to be output into the buffer, rather than the font being
painted on the screen.

If the buffer becomes full, or any fonts are painted which do not have any
outlines, the error status is stored at the end of the buffer, instead of
the terminating 0 word.  No error is reported at the time, but the status
can be interrogated when the output redirection ceases.  Note that output
will continue to go into the buffer after an error occurs, unless it was a
'Buffer Overflow' error.


SWI Font_MakeBitmap
    R0 -> bit array (cf. Font_UnCacheFont), 0 if not interested
    R1-R7 = other parameters (cf. Font_FindFont)
    ensure that outlines are used as the source
    if non-outlines are already cached, Font_UnCacheFont is called

SWI Font_UnCacheFont
    R0 -> set of 8 words, on exit bit set if font data was uncached
    R0 = 0 => don't bother
    R1 -> name of font file which is to be altered
    Any occurrences of this data in the font cache must be flushed,
      and the file closed.  Handles onto the font remain valid, and when
      data is next requested from the file, the index is rescanned etc.  The
      bit array pointed to by R0 is updated so the caller can see which
      fonts were affected.
    This is useful for Font_MakeBitmap and also for the Font Editor.

SWI Font_ListSizes
In  R1 --> font name
    R2 = 0 for first size, else as returned from Font_ListSizes
    R3 = 0 => return 1-bpp sizes, 1 => return 4-bpp sizes
Out R2 < 0 => no more, else value to pass back in next time
      R3,R4 = x/y size of font (1/16ths point)
      R5,R6 = x/y dots per inch
      At the end, if R2=-2 on exit, this means:
          (1) there is an outline file, if R3=0 on entry
          (2) there is an x90y45 file, if R3=1 on entry
              In this case R3-R6 define the size of the master font

x90y45->name of another file (f9999x9999)
    Note that in this case Font_ListSizes will still say that there is an
    x90y45 file, giving the size of the actual font master in R3-R6.

!Fonts:
    make/delete 4-bpp masters - show list of sizes
    set FontMax0..7 (histograms)
    set/show fontcache size min/max
    show usage of font cache?
