> scsi::Lullaby.$.RiscOS+.Sources.Fonts.Doc.Since298

Title; Font Manager changes since version 2.98
Author; David De Vorchik
History;
        17-Nov-91 DDV Created
        19-Nov-91 DDV Added notes on Font_LookupFont
        22-Nov-91 DDV Added Font_ReadFontMax and Font_WriteFontMax apply to CMOS bits
         2-Feb-92 DDV Notes on FontV included
         2-Feb-92 DDV Updated to reflect reality.
        30-Mar-93 JSR Added version 3.10 details
        26-Aug-93 amg Added version 3.11 details

This document attempts to explain the changes within the Font Manager since
version 2.98, these changes mainly relate to features being intergrated into
the 'green' release.
             

Summary of changes
==================

Version 2.98

  * New SWIs to Find/Apply fields.

Version 3.00

  * Fonts can now be defined with the non-zero winding rule, this aids
    Type-1 conversion where all fonts use this rule rather than non-zero.

  * SwitchOutputToBuffer can now generate data with the non-zero rule.
            
Version 3.01

  * FontMax1-5 settings are now stored in points rather than pixels, this
    effects the configuration and Font_Read/SetFontMax SWIs.

Version 3.02

  * New Font_LookupFont SWI to return characteristics of a particular font.
  
Version 3.03

  * Font_ReadFontMax and Font_SetFontMax bits to modify CMOS RAM.
  * Support for FontV included.

Version 3.10

  * Switch to OS_SetColour to store, set and restore colours when rendering
        draw paths to screen.
        
Version 3.11

  * Make the code added in 3.10 actually work

Coming soon (maybe):

  * Font_LookupFont to return : kerning possible?


Changes to existing SWIs 
========================

Font_ReadDefn
-------------

  In    R0 = handle of font
        R1 --> buffer address (for name)
        R3 = &4C4C5546 ('FULL') to return full information about encoding + matrix
             R1 can be 0 on entry, to just read size required
  Out
        if R3='FULL' on entry, then
           if R1=0 on entry, then
              R2 = size of buffer required to hold name
              R3-R7 corrupt
           else
              [R1] contains full information, ie. \f<name> \e... \m...
              R2,R3 = x,y point size * 16
              R4,R5 = x,y resolution
              R6 = 'age', ie. no of accesses since last time font was used
              R7 = reference count
           endif
        else
           [R1..] = name (copied to user buffer)
           R2,R3 = x,y point size * 16
           R4,R5 = x,y resolution
           R6 = 'age', ie. no of accesses since last time font was used
           R7 = reference count
        endif

This SWI has been extended to return the full information relating to a
font, ie. what encoding and matrix is applied.  The SWI can also return the
size of buffer needed to get the font name rather than the calling assuming
a 40 byte buffer is enough.


Font_SetFontMax
---------------

  In    R0 = value of FontMax (bytes)
                bit 31 set => apply change to CMOS aswell

        R1-R5 = new values of FontMax1..FontMax5 in points
        R6,R7 = 0 (reserved)

On entry R1-R5 have changed to accept the values in points rather than
pixels * 72 * 16.  When this SWI is made the cache is scanned and all fonts
are updated to reflect the new thresholds.

The CMOS configuration values are not effected, unless R0 bit 31 is set.


Font_ReadFontMax
----------------
           
  In    R0 = &534F4D43 ('CMOS')
            
  Out   if R0 = &534F4D43 then (read from CMOS)
              R0 = value of FontMax (bytes)                     
              R1-R5 = values of FontMax1..FontMax5 in points

        else (current values)
              R0 = value of FontMax (bytes)                     
              R1-R5 = values of FontMax1..FontMax5 in points

        R6,R7 = 0 (reserved)

This SWI now returns the threshold values (R1-R5) in points rather than
the old format of pixels * 72 * 16.

The values are rescaled when a font is found to the specified resolution.

If R0 ='CMOS' on entry then the values are obtained from the CMOS RAM rather
than the current values stored within the Font Managers workspace.
                         

New SWIs
========

Font_FindField (&400A6)
--------------

  In    R1 -> font string
        R2 = character code of qualifier required
  Out   R1 -> value following qualifier in string, or preserved
        R2 preserved => field was present, else R2=0 => not present

This call given a font string will find the index relating to the specified
qualifier.

Note that in the general case the "F" field is space-terminated, while all
others are ctrl-char terminated


Font_ApplyFields (&400A7)
----------------

  In    R0 -> original font string
        R1 -> set of fields to be added (in format of a font string)
        If R2=0 Then R3 = buffer size so far (1 to include the terminator)
        else R2 -> output buffer, R3 = buffer size (inc. room for terminator)
  Out   If R2=0 on entry, then R3 is incremenented by the length of the output string (ex. terminator)
        else R2 -> string (in buffer), 0-terminated, R3 = buffer size remaining
        Note that a qualifier with a null value in the second string deletes the corresponding string in the result

This routine attempts to insert a new set of feilds into the specified
string, the routine attempts to replace existing feilds.

This operation is performed in two passes:

 pass 1: copy fields in [R0] from [R1] if present, else [R0]
 pass 2: copy fields in [R1] from [R1] if not present in [R0]


Font_LookupFont (&400A8)
---------------

  In    R0 = font handle / =0 use current
        R1 -> font name / =0 use handle specified in R0        ; NYI
        R2 = flags
                all bits reserved and must be zero
  Out   R0,R1 = preserved, unless error where R0 -> error block
        R2 = characteristics of font
                bit 0 set => font is old 'x90y45' bitmap format
                bit 1 set => font is in ROM
                bit 8 set => font is monochrome only
                bit 9 set => font is filled with non-zero rule, rather than even-odd
                all other bits reserved and must be zero
        R3-R7 = undefined

This call allows the caller to enquire about a particular font.

On exit R2 contains a set of flags describing how the font is rendering
and other characteristics.

Bit 0 indicates an old style font, ie. one which cannot be rotated, no be
re-encoded.  Bit 1 indicates that the font is cached directly from ROM.

Bits 8 and 9 describe how the font will be rendered.  Bit 8 indicates that
the font will only be rendered in monochrome, no matter what FontMax2 is set
to.  Bit 9 indicates the filling rule which will be applied.

Please note it is only possible to request information on a font by handle,
and not by name (ie. R1 should always be zero).


Font Manager and its FontV
==========================

The Font Manager now uses the FontV to allow the indirection of font calls
to different modules.  This allows different areas of the manager to be replaced
without needing large chunks replacing.

The FontV is called with the following parameters:

        in      R8 = index of the SWI being called
                WsPtr -> workspace for owner
        out     R0-R7 may contain different parameters

IRQs are disabled, and should be enabled.
