|
www.riscos.com Technical Support: |
A font is a set of characters of a given type style. The Font Manager provides facilities for painting characters of various sizes and styles on the screen.
To allow characters to be printed in any size, descriptions of fonts can be held in files as size-independent outlines, or pre-computed at specific sizes. The Font Manager allows programs to request font types and sizes by name, without worrying about how they are read from the filing system or stored in memory.
The Font Manager also scales fonts to the desired size automatically if the exact size is not available. The fonts are, in general, proportionally spaced, and there are facilities to print justified text - that is, adjusting spaces between words to fit the text in a specified width.
An anti-aliasing technique can be used to print the characters. This technique uses up to 16 shades of colour to represent pixels that should only be partially filled-in. Thus, the illusion is given of greater screen resolution.
The Font Manager can use hints, which help it scale fonts to a low resolution while retaining maximum legibility.
References in this chapter to the RISC OS 2 Font Manager describe the outline Font Manager that is supplied with Release 1.02 of Acorn Desktop Publisher. The RISC OS 2 ROM contains an earlier version of this Font Manager called the bitmap Font Manager. This is no longer supported, and you should always use the outline Font Manager.
The Font Manager can be divided internally into the following components:
Much of the Font Manager deals with an internal measurement system, using millipoints. This is 1/1000th of a point, or 1/72000th of an inch. This system is an abstraction from the physical characteristics of the VDU. Text can therefore be manipulated by its size, rather than in terms of numbers of pixels, which will vary from mode to mode.
The Font Manager also uses OS coordinates as a measurement system. There are defined to be 180 OS units per inch. This is the coordinate system used by the VDU drivers, and is related to the physical pixel layout of the screen. Calls are provided to convert between these two systems, and even change the scaling factor between them.
A SWI is provided to scan through the list of available fonts. This allows a program to present the user with a list to select from. The list is cached and so is fast to access - except under RISC OS 2, where it's consequently a slow process to get the font list unless you cache it yourself, which we recommend.
Another SWI will return a handle for a given font style. A handle is a number that the Font Manager uses as an internal reference for the font style. This is like an Open command in a filing system. The equivalent of Close is also provided. This tells the Font Manager that the program has finished with the font.
There is a SWI to make a handle the currently selected one. This will be used implicitly by many calls in the Font Manager. It can be changed by commands within a string while painting to the VDU.
Cacheing is the technique of storing one or more fonts in a designated space in memory. The cacheing system decides what gets kept or discarded from its space. Two CMOS variables control how much space is used for cacheing. One sets the minimum amount, which no other part of the system will use. The other sets a threshold beyond which the Font Manager will discard as much cached information as possible in an endeavour not to let the cache grow. However, if many more fonts are in use than are reasonable for the configured threshold, the Font Manager may be forced to let the cache grow past this point.
You should adjust these settings to suit the font requirements of your application. If too little is allowed, then the system will have to continually re-load the fonts from file, which considerably slows response. If it is too large, then you will use up memory that could be used for other things.
The command *FontList is provided to show the total and used space in the cache, and what fonts are held in it. This is useful to check how the cache is occupied.
The anti-aliasing system uses up to 16 colours, depending on the screen mode. It will try, as intelligently as possible, to use these colours to shade a character giving the illusion of greater resolution.
The colour shades start with a background value, which is usually the colour that the character is painted onto. They progress up to a foreground colour, which is the desired colour for the character to appear in. This is usually what appears in the centre of the character. Both of these can be set to any valid logical colour numbers.
In between background and foreground colours can be a number of other logical colours. There is a call to program the palette so that these are set to graduating intermediate levels. The points of transition are called thresholds. The thresholds are set up so that the gradations produce a smooth colour change from background to foreground.
For screen modes with more than 16 colours, this sets up a 'pseudo palette' that indirects into the real palette.
A string can be painted into the VDU memory. As well as printable characters which are displayed in the current font style, there are non-printing control sequences, used in much the same way as those in the VDU driver. They can perform many operations, such as:
By using these control sequences, a single string can be displayed with as many changes of these characteristics as required.
Many SWIs exist to measure various attributes of fonts and strings. With a font, you can determine the smallest box which is large enough to contain any character in the set. This is called the font bounding box. You can also check the bounding box of an individual character.
With a string, you can measure its bounding box, or check where in the string the caret would be for a given coordinate. The caret is a special cursor used with fonts. It is usually displayed as a vertical bar with loops on each end.
A number of Font Manager operations can be performed through VDU commands. These have been kept for compatibility and you should not use them, as they may be phased out in future versions.
An easy way to introduce you to programming with the Font Manager is to use a simple example. It shows how to paint a text string on the screen using Font Manager SWIs. Further on in this section is a more detailed explanation of these and all other font SWIs.
Here is the sequence that you would use:
The description of character and font sizes comes from specialist files called metrics files. The numbers in these files are held in units of 1/1000th of an em. An em is the size of a point multiplied by the point size of the font. For example, in a 10 point font, an em is 10 points, while in a 14 point font it is 14 points. The Font Manager converts 1000ths of ems into 1000ths of points, or millipoints, to use for its internal coordinate system. A millipoint is equal to 1/72000th of an inch. This has the advantage that rounding errors are minimal, since coordinates are only converted for the screen at the last moment. It also adds a level of abstraction from the physical characteristics of the target screen mode.
Unfortunately, the coordinates provided for plot calls are only 16 bits, so this would mean that text could only be printed in an area of about 6/7ths of an inch.
Therefore, the font painter takes its initial coordinates from the user in the same coordinates as the screen uses, which are known as OS units. To make the conversion from OS units to points, the font painter assumes by default that there are 180 OS units to the inch. You can read and set this scale factor, which you may find useful to accurately calibrate the on screen fonts, or to build high resolution bitmaps.
When the font painter moves the graphics point after printing a character, it does this internally to a resolution of millipoints, to minimise the effect of cumulative errors. The font painter also provides a justification facility, to save you the trouble of working the positions out yourself. The application can obtain the widths of characters to a resolution of millipoints.
A pair of routines can be used to convert to and from internal millipoint coordinates to the external OS coordinates. Font_ConverttoOS will go from millipoints, while Font_Converttopoints will go to them.
The scaling factor that the above SWIs (and many others in the Font Manager) use can be read with Font_ReadScaleFactor. You can also set this with Font_SetScaleFactor, although we recommend that you don't do so under the desktop, as other applications may assume the default. If you must alter this value, you should at the very least restore it before polling the Wimp.
The font files relating to a font are all held in a single directory structure consisting of one or more font subdirectories (for different weights and styles/angles) and one or more encoding subdirectories. All Acorn font names should conform to:
fontname.[weight.[style]]
The weight element can only be omitted if there is no style element either, eg for a Symbol font.
Files held within this structure are:
| Filename | Contents | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| IntMetrics | metrics information for default encoding | ||||||||||||||
| IntMetric0 | metrics information for encoding /Base0 | ||||||||||||||
| IntMetricn | metrics information for encoding to /Basen
| encoding.x90y45
| old format pixel file (4-bits-per-pixel) for encoding
| encoding.f9999x9999
| new format pixel file (4-bits-per-pixel) for encoding
| encoding.b9999x9999
| new format pixel file (1-bits-per-pixel) for encoding
| Outlines
| outline file for default encoding
| Outlines
| 0 outline file for encoding /Base0
| Outlines
| n outline file for encoding to /Basen
| Messagesn
| mapping of font identifiers to names for country n
| |
The '9999's referred to above mean 'any decimal number in the range 1 - 9999'. They refer to the pixel size of the font contained within the file, which is equal to:
(font size in 1/16ths of a point) × dots per inch / 72
so, for example, a file containing 4-bits-per-pixel 12 point text at 90 dots per inch would be called f240x240, because 12 × 16 × 90 / 72 = 240.
The formats of these files are detailed in Appendix E: File formats on Draw files.
The default encoding for an alphabetic font (as opposed to symbol fonts, which have a fixed encoding) depends on the alphabet number of the current encoding. The encoding /Base0 includes all the characters supplied with a font; for an example of it, and of the Latin... encodings, see the file:
For details of the different RISC OS character sets, see Table D: Character sets.
The minimal requirement for a font is that it should contain an IntMetrics file, and an Outlines file (which we strongly urge you to include) or an x90y45 file. In addition, it can have any number of f9999x9999 or b9999x9999 files, to speed up the cacheing of common sizes.
If outline data or scaled 4-bpp data is to be used as the source of font data it is first loaded into a 'master' font in the cache, which can be shared between many 'slave' fonts at various sizes. There can be only one master font for a given font identifier, regardless of size, whereas each size of font requires a separate slave font. If the data is loaded directly from a bitmap file into the slave font, the master font is not required.
Font identifiers are the names of font subdirectories, and are used for all programmer's interfaces to the Font Manager, such as SWIs. They are constant across all countries. Font names are the local form of a font identifier for a particular country, and are used for all user interfaces to the Font Manager, such as menus.
Font names are obtained by looking in the file Fontprefix.Messagescountryno, using the font identifier as a key. For example, a UK Messages file would be named Messages1. This allows internationalisation by having an extra level of indirection between font identifiers and font names. The file Fontprefix.Messages is used as a default if the country-specific file is not present.
The Font Manager only actually scans the font directory if no Messages file can be found. Of course, reading a Messages file is much faster than scanning the font directory.
Messages files allow font paths to become much more effective, since new font directories can be added to the list of known fonts without losing references to other font directories. This and the fact that the Font Manager knows exactly where each font is held makes it possible for a user to put fonts on several floppy discs and still use them effectively. Messages files also allow you to set the default font in a family (eg selecting just 'Trinity' in a font menu can be made to select 'Trinity.Medium', rather than just the first entry in the sub-menu).
Details of the format of Messages files are in Appendix E: File formats on Draw files - just as for all other font file formats.
The Font Manager uses the path variable Font$Path when it searches for fonts. This contains a list of full pathnames - each of which has (as in all ...$Path variables) a trailing '.' - which are, in turn, placed before the requested font identifier. The Font Manager uses the first directory that matches, provided it also contains an IntMetrics file. Because the variable is a list of path names, you can keep separate libraries of fonts.
Early versions of the Font Manager used the variable Font$Prefix to specify a single font directory. For compatibility, the Font Manager looks when it is initialised to see if Font$Path has been defined - if not, it initialises it as follows:
*SetMacro Font$Path <Font$Prefix>.
This ensures that the old Font$Prefix directory is searched if you haven't explicitly set up the Font Manager to look elsewhere. The trailing '.' is needed, as Font$Prefix does not include one, and Font$Path requires one.
*FontCat will list all the fonts that can be found using Font$Path.
Applications which allow the user access to fonts should call Font_ListFonts repeatedly to discover the list of fonts available. This is normally done when the program starts up. The same call can be used with different parameters to build a menu of available fonts (but not under RISC OS 2).
The commands *FontInstall, *FontRemove and *FontLibrary add directories to Font$Path, or remove them. Service_FontsChanged is then issued to notify module-based applications that they should update their list of available fonts by calling Font_ListFonts again. These commands are not available under RISC OS 2, but where possible, you should use them. (Non module-based applications must call Font_ListFonts each time they require a list of available fonts, as they have no way of knowing when the list has changed.)
Under RISC OS 2 families of fonts are often found in a separate font 'application' directory, the !Run file of which RMEnsures the correct Font Manager module from within itself, and then either adds itself to Font$Path or resets Font$Path and Font$Prefix so that it is the only directory referenced.
In order to ensure that the user can access the new fonts available, applications running under RISC OS 2 should check whether the value of Font$Path or Font$Prefix has changed since the list of fonts was last cached, and recache the list if so. A BASIC program could accomplish this as follows:
size% = &200 DIM buffer% size% : REM this could be a scratch buffer ... SYS "OS_GSTrans","<Font$Prefix> and <Font$Path>",buffer%,size%-1 TO ,,length% buffer%?length% = 13 :REM ensure there is a terminator (13 for BASIC) IF $buffer%<>oldfontpath$ THEN oldfontpath$ = $buffer% PROCcache_list_of_fonts ENDIF
Note that if the buffer overflows the string is simply truncated, so it is possible that the check may miss some changes to Font$Prefix. However, since new elements are normally added to the front of Font$Path, this will probably not matter.
The application could scan the list of fonts when it started up, remembering the value of Font$Path and Font$Prefix in oldfontpath$, and then make the check described above just before the menu tree containing the list of fonts was about to be opened.
Alternatively the application could scan the list of fonts only when required, by setting oldfontpath$="" when it started up, and checking for Font$Path changing only when the font submenu is about to be opened (using the Message_MenuWarning message protocol).
In order to use a font, Font_FindFont must be used. This returns a handle for the font, and can be considered conceptually like a file open. In order to close it, Font_LoseFont must be used.
Font_ReadDefn will read the description of a handle, as it was created with Font_FindFont.
In order for a handle to be used, it should be set as the current handle with Font_SetFont. This setting stays until changed by another call to this function, or while painting, by a character command to change the handle.
Font_CurrentFont will tell you what the handle of the currently selected font is.
The size of the cache can be set with two commands. *Configure FontSize sets the minimum that will be reserved. This allocation is protected by RISC OS and will not be used for any other purpose. Running the Task Display from the desktop and sliding the bar for font cache will change this setting until the next reset.
Above this amount, *Configure FontMax sets a maximum amount of memory for font cacheing. The Font Manager will endeavour not to use more than this, but may have to should there be many more fonts in use than are reasonable for the configured FontMax.
The difference between FontSize and FontMax is taken from unallocated free memory as required to accommodate fonts currently in use. If other parts of the system have used up all this memory, then fonts will be limited to FontSize. If there is plenty of free unallocated memory, then FontMax will stop font requirements from filling up the system with cached fonts.
*FontList will generate a list of the size and free space of the cache, as well as a list of the fonts currently cached. Font_CacheAddr can be used in a program to get the cache size and free space.
When a program calls Font_LoseFont, the font may not be discarded from memory. The cacheing system decides when to do this. A usage count is kept, so that it knows when no task is currently using it. An 'age' is also kept, so that the Font Manager knows when it hasn't been used for some time.
The cache format, and the algorithms used for cacheing characters, change from release to release. You must not directly access the cache.
You can use the commands *SaveFontCache to save the font cache in a known state. You can then use *LoadFontCache to reload it later, but there are restrictions when doing so:
Using saved font caches can be a useful speed-up for your applications.
Colour selection with the Font Manager involves the range of logical colours that are used by the anti-aliasing software and the physical colours that are displayed.
The logical colour range required is set by Font_SetFontColours. This sets the background colour, the foreground colour and the range of colours in between.
Font_SetPalette duplicates what Font_SetFontColours does, and uses two extra parameters. These specify the foreground and background physical colours, using 4096 colour resolution. Given a range of logical colours and the physical colours for the start and finish of them, this SWI will program the palette with all the intermediate values.
There can be a maximum of 16 colours used. For screen modes having more than 16 colours, the above calls instead set up a 'pseudo palette' that provides for up to 16 indirect references to colours in the real palette. Such a 'pseudo palette' must be defined before trying to paint fonts.
It must be strongly emphasised that if the program you are writing is going to run under the Wimp environment then you must not use Font_SetPalette. It will damage the Wimp's colour information. It is better to use Wimp_SetFontColours, or ColourTrans_SetFontColours, or a control sequence 19,... in a string passed to Font_Paint; these all use colours that are already in the palette.
The setting of intermediate levels uses threshold tables. These can be read with Font_ReadThresholds or set with Font_SetThresholds. They use a lookup table that is described in Font_ReadThresholds.
Font_Paint is the central SWI that puts text onto the screen. It commences painting with the current handle, set with Font_SetFont. Printable characters it displays appropriately, using the current handle. Using Font_Paint, you can justify the text, back it with a rubout box, transform it, and/or apply kerning to its characters.
A number of embedded control sequences (introduced by control characters) change the way the string is painted:
Note that these are not compatible with VDU commands. Any non-printing characters not in the above list will generate an error, apart from 0, 10 and 13 (which are the only valid terminators).
There are a number of calls to return information about a string or character. Most of these are obsolete calls from earlier versions of the Font Manager, which are still supported for backward compatibility.
To get information on a string, you should call Font_ScanString. To get information on a character, you should call Font_CharBBox.
After using Font_ScanString, you can call Font_FutureFont. This will return what the font and colours would be if the string was passed through Font_Paint.
If the pointer is clicked on a string, and the caret needs to be placed in between two characters, it is necessary to calculate where on the string it would be. Again, Font_ScanString can do this.
You can plot the caret at a given height, position and colour using Font_Caret. Its height should be adjusted to suit the point size of the font it is placed with. The information returned from Font_ScanString would be appropriate for this adjustment.
Where you are using an external printer (eg. PostScript) which has a larger range of fonts than those available on the screen, it can often be useful to use a similar-looking font on the screen, using the appropriate metrics (ie spacing) for the printer font.
The Font Manager provides a facility whereby a font can be created which has its own IntMetrics file, matching the appropriate font on the printer, but uses another font's characters on the screen.
This is done by putting a file called 'Outlines' in the font's directory which simply contains the identifier of the appropriate screen font to use. The Font Manager will use the IntMetrics file from the font's own directory, but will look in the other font's directory for any bitmap or outline information.
Under RISC OS 3 and later, the identifier can contain a transformation matrix specified in the same way as the font identifier passed to Font_FindFont. This allows simple generation of oblique fonts. For an example, see the RISC OS 3 file Resources:$.Fonts.Corpus.Oblique.Outlines0.
For efficiency, the Font Manager caches the value in millipoints of the last y coordinate to which it painted, and reuses that value if it paints to the same y coordinate next time. However, this cached value does not take account of screen eigen values, and both RISC OS 2 and RISC OS 3 (version 3.00) fail to notice a mode change and update the cached y position to take account of the new eigen values. Consequently the Font Manager will paint to the wrong y position on the screen.
To work around this, on receipt of a Service_ModeChange your application should call Font_Paint to paint a null string at coordinates (-1, -1), which is off the screen. This will invalidate the cached value, so a subsequent paint to the same y coordinate as before the mode change will then work correctly. For example you would make this call in BASIC:
SYS "Font_Paint",,"",&10,-1,-1
--
R0 = version number
R2 = total size of font cache (bytes)
R3 = amount of font cache used (bytes)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
The version number returned is the actual version multiplied by 100. For example, version 2.42 would return 242.
This call also returns the font cache size and the amount of space used in it.
*FontList can be used to display the font cache size and space.
None
None
R1 = pointer to font identifier (terminated by a Ctrl char)
R2 = x point size × 16 (ie in 1/16ths point)
R3 = y point size × 16 (ie in 1/16ths point)
R4 = x resolution in dots per inch (0 
USE DEFAULT_ -1 use current)
R5 = y resolution in dots per inch (0 USE DEFAULT_ -1 use current)
R0 = font handle
R1 - R3 preserved
R4 = x resolution in dots per inch
R5 = y resolution in dots per inch
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call returns a handle to a font whose identifier, point size and screen resolution are passed. It also sets it as the current font, to be used for future calls to Font_Paint etc.
The font identifier can also have various qualifiers added to it, which are a ' \ ' followed by an identifying letter and the value associated with the qualifier. These qualifiers are not supported by RISC OS 2. If the string does not start with a ' \ ', it is assumed that it is a font identifier.
The strings following qualifiers must not contain ' \ ', as this denotes the start of the next qualifier.
The possible qualifiers are:
| \Fidentifier | font identifier (as for earlier implementations of Font_FindFont) |
| \ft name | territory number for font name, followed by the font name |
| \Eidentifier | encoding identifier |
| \et name | territory number for encoding name, followed by the encoding name |
| \Mmatrix | transformation matrix to apply to this font |
where:
Spaces are significant in the above syntaxes; you must include them only where shown.
The font identifier is the name of the font directory without the Font$Path prefix, and is invariant in any territory. These are used in all programmer's interfaces to the Font Manager, such as SWIs. The font name is the name of the font (ie the one displayed to the user) in the given territory. These are used in all user interfaces to the Font Manager, such as menus.
If Font_FindFont fails to find the font, an error message Font 'name' not found is returned, where name is the font name if the current territory is the same as the one in the string, and is the font identifier otherwise.
Applications should store the entire string returned from Font_DecodeMenu in the document, so that if a user loads the document without having the correct fonts available, the font name - rather than the identifier - can be returned, as long as the user is in the same territory.
The '\E' (encoding) field indicates the appropriate encoding for the font itself. This field is only supplied by Font_DecodeMenu if the font is deemed to be a 'language' font, ie one whose encoding depends on the territory. Other fonts are thought of as 'Symbol' fonts, which have a fixed encoding.
Note that Font_DecodeMenu will return a font identifier of the following form:
\Ffontid\fterritory fontname
To apply a particular encoding to a font, remember to eliminate the existing encoding fields (if present) first. Note that no field is allowed to contain a '\'.
\Eencid\eterritory encname\Ffontid\fterritoryfontname
Since fontid\fterritory fontname is also accepted by Font_FindFont, when prepending '\Eencid\eterritory encname' on the front, you should also put '\F' on the front of the original string if it did not start with '\'.
In BASIC, this looks like:
REM original$ is the original string passed to Font_FindFont REM encoding$ is the string returned from Font_DecodeMenu REM typically "\E<enc_id>\e <territory> <enc_name>" REM result is the new string to be passed to Font_FindFont DEF FNapply_encoding_to_font(original$,encoding$) IF LEFT$(original$,1)<>"\" THEN original$ = "\F"+original$ original$ = FNremove(original$,"\E") original$ = FNremove(original$,"\e") = encoding$ + original$ REM this function removes the specified field from the string REM eliminates all characters from b$ to "\" DEF FNremove(a$,b$) LOCAL I%,J% I% = INSTR(a$,b$) IF I%=0 THEN =a$ :REM nothing to eliminate J% = INSTR(a$+"\","\",I%+1) :REM searches from I%+1 = LEFT$(a$,I%-1)+MID$(a$,J%)
In fact it is not strictly necessary to remove the original encoding fields from the font identifier, since an earlier occurrence of a field overrides a later one; but if this is not done then the length of the total string will continue to grow every time an encoding is altered.
R0 = font handle
R0 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call tells the Font Manager that a particular font is no longer required.
None
R0 = font handle
R1 = pointer to buffer to hold font identifier, or 0 to return required size of buffer - if R3 = 'FULL' on entry
R3 = &4C4C5546 ('FULL') to return full information about encoding and matrix
R0, R1 preserved
R2 = x point size × 16 (ie in 1/16ths point)
R3 = y point size × 16 (ie in 1/16ths point)
R4 = x resolution (dots per inch)
R5 = y resolution (dots per inch)
R6 = age of font
R7 = usage count of font
or, if R1 = 0 and R3 = 'FULL' on entry:
R0, R1 preserved
R2 = required buffer size to hold full information
R3 - R7 corrupted
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call returns a number of details about a font. The usage count gives the number of times that Font_FindFont has found the font, minus the number of times that Font_LoseFont has been used on it. The age is the number of font accesses made since this one was last accessed.
Note that the x resolution in a 132 column mode will be the same as an 80 column mode. This is because it is assumed that it will be used on a monitor that displays it correctly, which is not the case with all monitors.
By setting R3 to 'FULL', you can get the full font identifier, including such information as its transformation matrix and encoding. You can also find the required size of buffer to hold this information by setting R1 to 0 on entry. These features are not available in RISC OS 2.
None
R0 = font handle
R0 preserved
R1 = minimum x coordinate in OS units for the current mode (inclusive)
R2 = minimum y coordinate in OS units for the current mode (inclusive)
R3 = maximum x coordinate in OS units for the current mode (exclusive)
R4 = maximum y coordinate in OS units for the current mode (exclusive)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call returns the minimal area covering every character in the font. This is called the font bounding box.
You should use the SWI Font_CharBBox (see Font_CharBBox) in preference to this one.
None
R1 = pointer to string
R2 = maximum x offset before termination in millipoints
R3 = maximum y offset before termination in millipoints
R4 = character code of 'split' character (-1 for none); eg 32 for space
R5 = index of character to terminate by
R1 = pointer to character where the scan terminated
R2 = x offset after printing string (up to termination)
R3 = y offset after printing string (up to termination)
R4 = no of 'split' characters in string (up to termination)
R5 = index into string giving point at which the scan terminated
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call is used to calculate how wide a string would be in the current font.
The 'split' character is one at which the string can be split if any of the limits are exceeded. If R4 contains -1 on entry, then on exit it contains the number of printable (as opposed to 'split') characters found.
The string is allowed to contain control sequences, including font-change (26,font_handle) and colour-change (17,colour). After the call, the current font foreground and background call are unaffected, but a call can be made to Font_FutureFont to find out what the current font would be after a call to Font_Paint.
The string width function terminates as soon as R2, R3 or R5 are exceeded, or the end of the string is reached. It then returns the state it had reached, either:
By varying the entry parameters, the string width function can be used for any of the following purposes:
You should use the SWI Font_ScanString in preference to this one - except under RISC OS 2, where it is not available.
R0 = initial font handle (1 - 255) or 0 for current handle - if bit 8 of R2 is set
R1 = pointer to string
R2 = plot type:
use graphics cursor justification coordinates (bit 5 must be clear); else use R5 to justify (if bit 5 is set) or don't justify plot rubout box using either graphics cursor rubout coordinates (if bit 5 is clear) or R5 (if bit 5 is set); else don't plot rubout box coordinates are in OS units; else in millipoints use R5 as indicated below (bits 0, 4 must be clear) use R6 as indicated below (bit 4 must be clear) use R7 as indicated below use R0 as indicated above perform kerning on the string writing direction is right to left; else left to right
R1 - R7 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call writes a string to the screen, optionally justifying it, backing it with a rubout box, transforming it, and/or applying kerning to its characters.
RISC OS 2 ignores the values of R0 and of R5 - R7, and behaves as though bits 2,3 and 5 - 31 inclusive of R2 are clear.
Justification can be done in one of two ways, depending on the value of bits 0 and 5 of R2:
If both bits 0 and 5 of R2 are clear then the string isn't justified.
Similarly, there are two different ways to plot a rubout box. Bit 1 of R2 must be set; then:
In this case pixels are filled only if the pixel centre is enclosed, as in Draw_Fill.
To set the justification coordinates using the graphics cursor, you must have previously called a VDU 25 move command. Likewise, to set the rubout coordinates using the graphics cursor you must also have called VDU 25 twice, to describe the rectangle to clear: first the lower-left coordinate (which is inclusive), then the upper-right coordinate (which is exclusive). Thus, to specify both the justification and rubout coordinates, you must have made three VDU 25 moves, with the justify coordinates being last. The Font Manager rounds all these coordinates to the nearest pixel.
The coordinate block pointed to by R5 contains eight words: these give additional spacing to use to achieve justification, and coordinates for the rubout box. The values are in millipoints (since bit 4 of R2 must be clear):
If bit 6 of R2 is set (in which case bit 4 must be clear), the buffer pointed to by R6 contains a transformation matrix, held as six words. The first four words are 32-bit signed numbers, with a fixed point after bit 16 (ie 1 is represented by 1 << 16, which is 65536). The translations are in millipoints (since bit 4 of R2 must be clear):
| Offset | Value |
|---|---|
| 0 | four fixed point multipliers of transformation matrix |
| 16 | x, y coordinates for translation element of transformation matrix |
Subsequent matrices can be included within the string (not in RISC OS 2); they alter the matrix to the specified value, rather than being concatenated with any previous matrix. Such changes are made by including one of the following control sequences:
align, m1, m2, m3, m4
28, align, m1, m2, m3, m4, m5, m6
where align means 'sufficient null bytes for subsequent values to be word-aligned'. The equation for this is:
number of null bytes = (address of align + 3) AND NOT 3
m1 - m4 are little-endian 32-bit signed numbers with a fixed point after bit 16 (ie 1 is represented as 1 << 16, which is 65536).
m5 and m6 are the offsets, which - since bit 4 of R2 must be clear - are in millipoints. These values are assumed to be 0 if the 27,m1...m4 code is used.
To restore the unit matrix, use 27,align,65536,0,0,65536.
Note that underlining and rubout do not work correctly if the x axis is transformed so that it is no longer on the output x axis, or has its direction reversed. The effect when doing this should not be relied on.
If bit 10 of R2 is set, then text is written right to left, rather than left to right. In this case the width of each character is subtracted from the position of the current point before painting the character, rather than the width being added after painting it. Rubout and underline are also filled in from right to left.
When kerning, the kern pairs stored in the metrics file indicate the left and right hand characters of a pair, and the additional offset to be applied between the characters if this pair is found. Note that if the main writing direction is right to left, then the right hand character is encountered first, and the left hand one is encountered next.
Normally the string is painted up to its terminator. However, you can paint a substring by setting bit 7 of R2, and specifying the length of the substring in R7.
Note that the character at [R1,R7] may be accessed, to determine the character offset due to kerning (which in turn affects the underline width). This will not be a problem if the string has a terminator, and the R7=length facility is used only to extract substrings.
You can change the colour used by including this control sequence in the string:
19,r,g,b,R,G,B,max
This results in a call to ColourTrans_SetFontColours. Again, RISC OS 2 does not support this control sequence; but it does still provide ColourTrans_SetFontColours, which you should use in preference to 17,... or 18,... control sequences.
After the call, the current colours are updated to the last values set by this control sequences.
There are other control sequences that are supported by all versions of RISC OS, and that are similar to certain VDU sequences:
9,dx_low,dx_middle,dx_high
11,dy_low,dy_middle,dy_high
17,foreground_colour (+&80 for background colour)
18,background,foreground,font_colour_offset
21,comment_string,terminator (any Ctrl char)
25,underline_position,underline_thickness
26,font_handle
After the call, the current font and colours are updated to the last values set by control sequences.
Control sequences 9 and 11 allow for movement within a string. This is useful for printing superscripts and subscripts, as well as tabs, in some cases. They are each followed by a 3-byte sequence specifying a number (low byte first, last byte sign-extended), which is the amount to move by in millipoints. Subsequent characters are plotted from the new position onwards.
An example of moving in the Y direction (character 11) would look like the following example, where chr() is a function that converts a number into a character and move is the movement in millipoints:
MoveString = chr(11) +
chr(move AND &FF) +
chr((move AND &FF00) >> 8) +
chr((move AND &FF0000) >> 16)
Control sequence 17 will act as if the foreground or background parameters passed to Font_SetFontColours had been changed. Control sequence 18 allows all three parameters to that SWI to be set. See that SWI for a description of these parameters.
The underline position within control sequence 25 is the position of the top of the underline relative to the baseline of the current font, in units of 1/256th of the current font size. It is a sign-extended 8 bit number, so an underline below the baseline can be achieved by setting the underline position to a value greater than 127. The underline thickness is in the same units, although it is not sign-extended.
Note that when the underline position and height are set up, the position of the underline remains unchanged thereafter, even if the font in use changes. For example, you do not want the thickness of the underline to change just because some of the text is in italics. If you actually want the thickness of the underline to change, then another underline-defining sequence must be inserted at the relevant point. Note that the underline is always printed in the same colour as the text, and that to turn it off you must set the underline thickness to zero.
This is quite simple if neither x or y scaling is performed, and also if both x and y scaling is performed: the subpixel scaling directions relate to the output device axes.
When just horizontal or just vertical subpixel scaling is performed, it is sometimes necessary to swap over the sense of which is horizontal and which is vertical, in order to determine the 'size' of the font.
This goes for the other FontMaxn thresholds too, such as FontMax2, which determines whether characters should be anti-aliased. FontMax3 determines whether characters should be cached or not, and this must relate to the amount of memory taken up by the bitmaps.
Clearly it is not possible to apply scaffolding to characters which are transformed such that its new axes do not lie on the old ones. However, if the axes are mapped onto each other (eg a scale, rotation or reflection about an axis or 45-degree line) then scaffolding can still be applied. This can involve swapping over the x and y scaffolding. If a font is sheared, then scaffolding may be applied in one direction but not the other.
The bounding box of a transformed character cannot be determined purely by transforming the original bounding box of the character outline. This is because bounding boxes are axis-aligned rectangles, and character outlines are not, so the bounding box of the transformed character is typically smaller than that of the transformed bounding box.
Taking the bounding box of the transformed original bounding box is sufficient to work out a large enough box for outline to bitmap conversion, since not much memory is wasted (only one character is done at a time, and the character is 'shrink-wrapped' after conversion).
If a font has an encoding applied to it, then Font_Paint looks inside fontidentifier.encoding to find the bitmap files. This is because bitmap files are specific to one encoding.
Note that Font_MakeBitmap also generates its bitmap files inside the appropriate encoding subdirectory.
If the font has no encoding applied, the bitmap files are inside the font directory, as before.
Note that this means that encoding names must not clash with any of the filenames that normally reside within font directories, ie:
| IntMetrics[n] | n is optional and the prefix is truncated so it all fits in 10 characters |
| Outlines[n] | |
| x90y45 | |
| bnxn | n is a number from 1 - 9999 |
| fnxn |
R0 = colour (exclusive ORd onto screen)
R1 = height (in OS coordinates)
R2
R3, R4 in millipoints R3, R4 in OS coordinates
R0 - R4 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
The 'caret' is a symbol used as a text cursor when dealing with anti-aliased fonts. The height of the symbol, which is a vertical bar with 'loops' on the end, can be varied to suit the height of the text, or the line spacing.
The colour is in fact Exclusive ORd onto the screen, so in 256-colour modes it is equal to the values used in a 256-colour sprite. You can get these colours by calling ColourTrans_ReturnColourNumber.
R1 = x coordinate (in millipoints)
R2 = y coordinate (in millipoints)
R1 = x coordinate (in OS units)
R2 = y coordinate (in OS units)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call converts a pair of coordinates from millipoints to OS units, using the current scale factor. (The default is 400 millipoints per OS unit.)
Font_Converttopoints, Font_ReadScaleFactor,
Font_SetScaleFactor
None
R1 = x coordinate (in OS units)
R2 = y coordinate (in OS units)
R0 is corrupted
R1 = x coordinate (in millipoints)
R2 = y coordinate (in millipoints)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call converts a pair of coordinates from OS units to millipoints, using the current scale factor. (The default is 400 millipoints per OS unit.)
None
R0 = handle of font to be selected
R0 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call sets up the font which is used for subsequent painting or size-requesting calls (unless overridden by a command 26,font sequence in a string passed to Font_Paint).
You can also set the font by passing its handle in R0 when calling Font_Paint (see Font_Paint). Where possible, you should do so in preference to using this SWI.
None
--
R0 = handle of currently selected font
R1 = current background logical colour
R2 = current foreground logical colour
R3 = foreground colour offset
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call returns the state of the Font Manager's internal characteristics which will apply at the next call to Font_Paint.
The value in R3 gives the number of colours that will be used in anti-aliasing. The colours are f, f+1... f+offset, where 'f' is the foreground colour returned in R2, and offset is the value returned in R3. This can be negative, in which case the colours are f, f-1... f-|offset|. Negative offsets are useful for inverse anti-aliased fonts.
Offsets can range between -14 and +14. This gives a maximum of 15 foreground colours, plus one for the font background colour. If the offset is 0, just two colours are used: those returned in R1 and R2.
The font colours, and number of anti-alias levels, can be altered using Font_SetFontColours, Font_SetPalette, Font_SetThresholds and Font_Paint.
Font_Paint, Font_SetFont, Font_SetFontColours, Font_SetPalette, Font_SetThresholds
None
Check font characteristics after Font_StringWidth
--
R0 = handle of font which would be selected
R1 = future background logical colour
R2 = future foreground logical colour
R3 = foreground colour offset
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call can be made after a Font_StringWidth to discover the font characteristics after a call to Font_Paint, without actually having to paint the characters.
R1 = pointer to string
R2 = x offset in millipoints
R3 = y offset in millipoints
R1 = pointer to character where the search terminated
R2 = x offset after printing string (up to termination)
R3 = y offset after printing string (up to termination)
R4 = number of printable characters in string (up to termination)
R5 = index into string giving point at which it terminated
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
On exit, the registers give the nearest point in the string to the caret position specified on entry. This call effectively makes two calls to Font_StringWidth to discover which character is nearest the caret position. It is recommended that you use this call, rather than perform the calculations yourself using Font_StringWidth, though this is also possible.
You should use the SWI Font_ScanString in preference to this one - except under RISC OS 2, where it is not available.
R0 = font handle
R1 = ASCII character code
R2 = flags (bit 4 set return OS coordinates, else millipoints)
R0 preserved
R1 = minimum x of bounding box (inclusive)
R2 = minimum y of bounding box (inclusive)
R3 = maximum x of bounding box (exclusive)
R4 = maximum y of bounding box (exclusive)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
You can use this call to discover the bounding box of any character from a given font. If OS coordinates are used and the font has been scaled, the box may be surrounded by an area of blank pixels, so the size returned will not be exactly accurate. For this reason, you should use millipoints for computing, for example, line spacing on paper. However, the millipoint bounding box is not guaranteed to cover the character when it is painted on the screen, so the OS unit bounding box should be used for this purpose.
--
R1 = x scale factor
R2 = y scale factor
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
The x and y scale factors are the numbers used by the Font Manager for converting between OS coordinates and millipoints. The default value is 400 millipoints per OS unit. This call allows the current values to be read.
None
Set the internal to OS conversion factor
R1 = x scale factor
R2 = y scale factor
R1, R2 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
Applications that run under the Desktop should not use this call, as other applications may be relying on the current settings. If you must change the values, you should read the current values beforehand, and restore them afterwards. The default value is 400 millipoints per OS unit.
Font_ConverttoOS, Font_Converttopoints, Font_ReadScaleFactor
Scan for fonts, returning their identifiers one at a time; or build a menu of fonts
RISC OS 2-compatible mode (see below) return font identifier in buffer pointed to by R1 (or required size of buffer for next identifier if R1 = 0) return local font name in buffer pointed to by R4 (or required size of buffer for next name if R4 = 0) terminate strings with character 13, rather than character 0 return font menu definition in buffer pointed to by R1, and indirected menu data in buffer pointed to by R4 (or required sizes of buffers if R1 and R4 = 0) put 'System font' at head of menu tick font indicated by R6, and its submenu parent return list of encodings, rather than list of fonts![[NOT EQUAL]](../symbols/entities/8800.png)
0) 0) NO TICK_ 1 tick 'System font')
R1 preserved
R2 = updated counter and preserved flags if listing identifiers/names (-1 if no more to be listed); or preserved if building menu
R3 = required size of buffer pointed to by R1 (if R1 = 0 on entry); or 0 if building a font menu, and the menu is null; else length of data placed in buffer
R4 preserved
R5 = required size of buffer pointed to by R4 (if R4 = 0 on entry); else length of data placed in buffer
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call has two possible uses:
In this case you should first initialise R2. Only bits 16-18 and bit 22 may be set; all other bits must be clear. Then for each font/encoding you must call this SWI twice: the first time with the buffers set up to receive the name(s) of that font/encoding. Do not alter the value of R2 between calls. When R2 is -1 on exit, the last font/encoding has already been found, and any returned name(s) are invalid.
In this case you may only set bits 19-21 of R2 on entry. You should make the call twice: the first time with R1 and R4 set to zero to find the required sizes of buffers, and the second time with the buffers set up to receive the manu definition.
Fonts are found by searching the path given by the system variable Font$Path, and its subdirectories, for files ending in '.IntMetrics'. Likewise, encodings are searched for by searching the path given by the system variable Font$Path, and its subdirectories, for files of the form 'font_prefix.Encodings.encoding_id' (which are used to specify the encodings of the 'language' fonts, as opposed to the 'symbol' fonts, the encoding of which is fixed).
When such a file is found, the full name of the subdirectory is put in the buffer, terminated by a carriage return or null. If the same font/encoding name is found via different paths, only the first one will be reported. The local name is found from a Messages file, if present.
Possible errors are 'Buffer overflow' (R3 and/or R5 was too small), or 'Bad parameters' (the flags in R2 were invalid). If an error is returned, R2 = -1 on exit (ie listing fonts/encodings is terminated).
The Font Manager command *FontCat calls this SWI internally.
The Font Manager in the RISC OS 3 ROMs (ie Font Manager 3.07 or earlier) has a bug in its handling of indirected menu titles. To work around this, you must use MessageTrans to decode the 'FontList' token in the Fonts resource file; if its length is more than 12 characters you must set the 'indirected menu title' bit of the first menu item, and otherwise you must clear it.
In the 'RISC OS 2-compatible mode' (used if bits 16 - 31 of R2 are clear), this call works as if bits 16 and 18 of R2 were set on entry, bits 17 and 19 - 31 were clear, and R3 was 40 (irrespective of its actual value).
Under RISC OS 2, this call works as if bits 16 and 18 of R2 were set on entry, and bits 17 and 19 - 31 were clear (hence R4, R5 and R6 are ignored). However, R3 is used to point to the path to search; a value of -1 means that Font$Path is used instead.
If your program does not RMEnsure the current version of the Font Manager, you should therefore always use Font$Path to specify the path to search.
None
Change the current colours and (optionally) the current font
R0 = font handle (0 for current font)
R1 = background logical colour
R2 = foreground logical colour
R3 = foreground colour offset (-14 to +14)
R0 - R3 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call is used to set the current font (or leave it as it is), and change the logical colours used. In up to 16 colour modes, the three registers are used as follows:
The range specified must not exceed the number of logical colours available in the current screen mode, as follows:
| Colours in mode | Possible values of R1,R2,R3 to use all colours |
|---|---|
| 2 | 0,1,0 |
| 4 | 0,1,2 |
| 16 or 256 | 0,1,14 |
In a 16 colour mode, to use the top 8 colours, which are normally flashing colours, the values 8,9,6 could be used.
Note that 16 is the maximum number of anti-alias colours. In 256-colour modes, the background colour is ignored, and the foreground colour is taken as an index into a table of pseudo-palette entries - see Font_SetPalette.
R1 = background logical colour
R2 = foreground logical colour
R3 = foreground colour offset
R4 = physical colour of background
R5 = physical colour of last foreground
R6 = &65757254 ('True') to use 24 bit colours in R4 and R5
R1 - R6 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call sets the anti-alias palette.
If the program you are writing is going to run under the Wimp environment then you must not use this call. It will damage the Wimp's colour information. You must instead choose from the range of colours already available by using Wimp_SetFontColours or ColourTrans_SetFontColours instead.
The values in R1, R2 and R3 have the same use as in Font_SetFontColours. See the description of that SWI on the previous pages for the use of these parameters.
R4 and R5 contain physical colour setting information. R4 describes the background colour and R5 the foreground colour. The foreground colour is the dominant colour of the text and generally appears in the middle of each character.
The physical colours in R4 and R5 are of the form &BBGGRR00. That is, they consists of four bytes, with the palette entries for the blue, green and red guns in the upper three bytes. Bright white, for instance, would be &FFFFFF00, while half intensity cyan is &77770000. The current graphics hardware only uses the upper nibbles of these colours, but for upwards compatibility the lower nibble should contain a copy of the upper nibble.
Under RISC OS 2, this call sets the palette colour for the range described in R1, R2 and R3 using R4 and R5 to describe the colours at each end. It also sets the intermediate colours incrementally between those of R4 and R5. In non-256-colour modes, the palette is programmed so that there is a linear progression from the colour given in R4 to that in R5.
Under later versions of RISC OS, if R6 is set to the magic word 'True', this call treats the values in R4 and R5 as true 24-bit palette values (where white is &FFFFFF00, rather than &F0F0F000). Otherwise, for compatibility, palette values are processed as follows:
R4 = (R4 AND &F0F0F000) OR ((R4 AND &F0F0F000) >> 4)
R5 = (R5 AND &F0F0F000) OR ((R5 AND &F0F0F000) >> 4)
Thus the bottom nibbles of each gun are set to be copies of the top nibbles. Furthermore, this call now uses PaletteV to set palette entries in non-256-colour modes, and ColourTrans_ReturnColourNumber to match RGB values with logical colours in modes with 256 or more colours. If PaletteV is not intercepted, it calls OS_Word 12 to do so.
R1 = pointer to result buffer
R1 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call reads the list of threshold values that the Font Manager uses when painting characters. Fonts are defined using up to 16 anti-aliased levels. The threshold table gives a mapping from these levels to the logical colours actually used to paint the character.
The format of the data read is:
| Offset | Value |
|---|---|
| 0 | Foreground colour offset |
| 1 | 1st threshold value |
| 2 | 2nd threshold value |
| 3 | : |
| n | &FF |
The table is used in the following way. Suppose you want to use eight colours for anti-aliased colours, one background colour and seven foreground colours. Thus the foreground colour offset is 6 (there are 7 colours). The table would be set up as follows:
| Offset | Value |
|---|---|
| 0 | 6 |
| 1 | 2 |
| 2 | 4 |
| 3 | 6 |
| 4 | 8 |
| 5 | 10 |
| 6 | 12 |
| 7 | 14 |
| 8 | &FF |
When this has been set-up (using Font_SetThresholds), the mapping from the 16 colours to the eight available will look like this:
| Input | Output | Threshold |
|---|---|---|
| 0 | 0 | |
| 1 | 0 | |
| 2 | 1 | 2 |
| 3 | 1 | |
| 4 | 2 | 4 |
| 5 | 2 | |
| 6 | 3 | 6 |
| 7 | 3 | |
| 8 | 4 | 8 |
| 9 | 4 | |
| 10 | 5 | 10 |
| 11 | 5 | |
| 12 | 6 | 12 |
| 13 | 6 | |
| 14 | 7 | 14 |
| 15 | 7 |
Where the output colour is 0, the font background colour is used. Where it is in the range 1 - 7, the colour f+o-1 is used, where 'f' is the font foreground colour, and 'o' is the output colour.
You can view the thresholds as the points at which the output colour 'steps up' to the next value.
None
Defines the list of threshold values for painting
R1 = pointer to threshold data
R1 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call sets up the threshold table for a given number of foreground colours. The format of the input data, and its interpretation, is explained in the previous section.
This command should rarely be needed, because the default set will work well in most cases.
R1 = pointer to string
R2 = x offset in millipoints
R3 = y offset in millipoints
R4 = x justification offset
R5 = y justification offset
R1 = pointer to character where the search terminated
R2 = x offset after printing string (up to termination)
R3 = y offset after printing string (up to termination)
R4 = no of printable characters in string (up to termination)
R5 = index into string giving point at which it terminated
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
The 'justification offsets', R4 and R5, are calculated by dividing the extra gap to be filled by the justification of the number of spaces (ie character 32) in the string. If R4 and R5 are both zero, then this call is exactly the same as Font_FindCaret.
You should use the SWI Font_ScanString in preference to this one - except under RISC OS 2, where it is not available.
R1 = pointer to string
R1 = bounding box minimum x in millipoints (inclusive)
R2 = bounding box minimum y in millipoints (inclusive)
R3 = bounding box maximum x in millipoints (exclusive)
R4 = bounding box maximum y in millipoints (exclusive)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call measures the size of a string without actually printing it. The string can consist of printable characters and all the usual control sequences. The bounds are given relative to the start point of the string (they might be negative due to backward move control sequences, etc).
Note that this command cannot be used to measure the screen size of a string because of rounding errors. The string must be scanned 'manually', by stepping along in millipoints, and using Font_ConverttoOS and Font_CharBBox to measure the precise position of each character on the screen. Usually this can be avoided, since text is formatted in rows, which are assumed to be high enough for it.
You should use the SWI Font_ScanString in preference to this one - except under RISC OS 2, where it is not available.
R1 = pointer to 16 byte area of memory
R1 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call returns the 16 entry colour table to the block pointed to by R1 on entry. This contains the 16 colours used by the anti-aliasing software when painting text - that is, the values that would be put into screen memory.
None
R1 = font handle, or pointer to font identifier
R2 = x point size × 16
R3 = y point size × 16
R4 = x dots per inch
R5 = y dots per inch
R6 = flags
--
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call allows a particular size of a font to be pre-stored in the font's directory so that it can be cached more quickly. It is especially useful if subpixel positioning is to be performed, since this takes a long time if done directly from outlines.
The flags have the following meanings:
| Bit | Meaning when set |
|---|---|
| 0 | construct f9999x9999 (else b9999x9999) |
| 1 | do horizontal subpixel positioning |
| 2 | do vertical subpixel positioning |
| 3 | just delete old file, without replacing it |
| 4 - 31 | reserved (must be 0) |
Once a font file has been saved, its subpixel scaling will override the setting of FontMax4/5 currently in force (so, for example, if the font file had horizontal subpixel scaling, then when a font of that size is requested, horizontal subpixel scaling will be used even if FontMax4 is set to 0).
If the font has an encoding applied to it (ie if there was a '/E' qualifier in the Font_FindFont string, or if this is a 'language' font, which varies in encoding according to the territory), then the bitmaps are held inside a subdirectory of the font directory:
prefix.fontidentifier.encoding.
Note that Font_Paint also looks inside this directory to find the bitmaps.
R1 = pointer to full filename of file to be removed
R2 = recache flag (0 or 1 - see below)
--
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
If an application such as !FontEd wishes to overwrite font files without confusing the Font Manager, it should call this SWI to ensure that any cached information about the file is deleted.
The filename pointed to by R1 must be the full filename (ie in the format used by the Filer), and must also correspond to the relevant identifier as it would have been constructed from Font$Path and the font identifier. This means that each of the elements of Font$Path must be proper full pathnames, including filing system prefix and any required special fields (eg net#fileserver:$.fonts.).
The SWI must be called twice: once to remove the old version of the data, and once to load in the new version. This is especially important in the case of IntMetrics files, since the font cache can get into an inconsistent state if the new data is not read in immediately.
The 'recache' flag in R2 determines whether the new data is to be loaded in or not, and might be used like this:
SYS "Font_UnCacheFile",,"filename",0 ... replace old file with new one SYS "Font_UnCacheFile",,"filename",1
None
R0 = new value of FontMax (bytes)
R1 - R5 = new values of FontMax1 - FontMax5 (in points, or in pixels × 72 × 16 under RISC OS 2)
R6, R7 reserved (must be zero)
--
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call can be used to set the values of FontMax and FontMax1... FontMax5. Changing the configured settings will also change these internal settings, but Font_SetFontMax does not affect the configured values, which come into effect on Ctrl-Break or when the Font Manager is re-initialised.
This call also causes the Font Manager to search through the cache, checking to see if anything would have been cached differently if the new settings had been in force at the time. If so, the relevant data is discarded, and will be reloaded using the new settings when next required.
None
Read the FontMax values
--
R0 = value of FontMax (bytes)
R1 - R5 = values of FontMax1 - FontMax5 (in points, or in pixels × 72 × 16 under RISC OS 2)
R6, R7 may be corrupted
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call can be used to read the values of FontMax and FontMax1... FontMax5. It reads the values that the Font Manager holds internally (which may have been altered from the configured values by Font_SetFontMax).
R0 = font handle
R1 = pointer to buffer
R2 = length of buffer
R0 preserved
R1 = pointer to terminating null
R2 = bytes remaining in buffer
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call finds the directory prefix relating to a given font handle, which indicates where the font's IntMetrics file is, and copies it into the buffer pointed to by R1; for example:
ADFS::4.$.!Fonts.Trinity.Medium.
One use for this prefix would be to find out which sizes of a font were available pre-scaled in the font directory.
None
R0 = flags if R1 > 0, else reserved (must be zero)
R1 = pointer to word-aligned buffer, or:
R0 = previous flag settings
R1 = previous buffer pointer, incremented by space required for Draw file structure
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
After this call, any calls to Font_Paint will be redirected into the buffer, as a Draw file structure.
Each letter painted will be treated as a separate filled object, with the colours specified in the paint command.
The flags in R0 have the following meaning:
| Bit | Meaning when set |
|---|---|
| 0 | update R1, but don't store anything |
| 1 | apply 'hints' to the outlines |
| 4 | give error if bitmapped characters occur (this bit overrides bit 3) |
All other bits are reserved, and must be zero.
This call is not available in RISC OS 2.
On entry, the buffer must contain the following if it is to receive output:
| Size | Contents |
|---|---|
| 4 | 0 (null terminator) |
| 4 | size remaining, in bytes |
The Draw file structure is placed in the file before the null terminator, between (original R1) and (final R1 - 1). R1 still points to the null terminator; the terminator and free space count do not form part of the output data itself.
If bit 0 of R0 is set, output is not actually sent to the buffer, but the pointer is updated. This allows the size of the required buffer to be computed properly before allocating the space for it. Note that if bit 0 of R0 is set, R1 must initially be greater than 0 (a value of 8 is recommended, since the buffer must allow 8 bytes for the terminator and free space counter).
The rubout box(es) and any underlining are also sent to the buffer as a series of filled outlines. These will be in the correct order so as to be behind any characters which overlap them. The output will also take into account matrix transformations, font and colour changes, explicit movements, justification and kerning.
If bit 1 of R0 is set, the character outlines have hints applied to them at the current size. This means that they are not really suitable for scaling later on.
Any characters which are only available as bitmaps will either generate an error (if bit 4 of R0 is set), or not be output.
In this way drawing programs can turn on buffering, then proceed to draw text in the appropriate position and size, and end up with a series of Draw objects which represent the same thing. The set of objects that the Font Manager produces could easily be converted into a group by wrapping them suitably.
None
Reads the full metrics information held in a font's IntMetrics file
R0 = font handle
R1 = pointer to buffer for bounding box information, or 0 to read size of data
R2 = pointer to buffer for x width information, or 0 to read size of data
R3 = pointer to buffer for y width information, or 0 to read size of data
R4 = pointer to buffer for miscellaneous information, or 0 to read size of data
R5 = pointer to buffer for kerning information, or 0 to read size of data
R6 = 0
R7 = 0
R0 = file flags
R1 - R5 = size of data (0 if not present in file)
R6, R7 undefined
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call reads the full metrics information held in a font's IntMetrics file.
The flags in R0 have the following meaning:
| Bit | Meaning when set |
|---|---|
| 1 | kern pairs don't have x offsets |
| 2 | kern pairs don't have y offsets |
| 3 | there are more than 255 kern pairs |
All other bits are reserved, and you should ignore them.
Currently this call is not permitted on fonts which have a transformation matrix applied to them. It is recommended that the call is made on the untransformed version of the font, and the results then transformed appropriately. Note that when transforming bounding boxes, the resulting (axis-aligned) box is that which bounds all 4 transformed bounding box corners. When transforming x and y offsets (ie character widths), the last 2 numbers in the matrix (the offsets) should be ignored, since the new origin is also moved by these amounts, and they therefore cancel out.
This call is not available in RISC OS 2.
The format of the data in the buffers is as follows. Except where otherwise stated:
array[256] of groups of 4 words (x0, y0, x1, y1)
array[256] of words
array[256] of words
| Size | Description | ||
|---|---|---|---|
| 2 | x0 | maximum bounding box for font (16-bit signed) | |
| 2 | y0 | bottom-left (x0, y0) is inclusive | |
| 2 | x1 | top-right (x1, y1) is exclusive | |
| 2 | y1 | all coordinates are in millipoints | |
| 2 | default x offset per char (if flags bit 1 is set), in millipoints (16-bit signed) | ||
| 2 | default y offset per char (if flags bit 2 is set), in millipoints (16-bit signed) | ||
| 2 | italic h-offset per em (-1000 × TAN(italic angle)) (16-bit signed) | ||
| 1 | underline position, in 1/256th em (signed) | ||
| 1 | underline thickness, in 1/256th em (unsigned) | ||
| 2 | CapHeight in millipoints (16-bit signed) | ||
| 2 | XHeight in millipoints (16-bit signed) | ||
| 2 | Descender in millipoints (16-bit signed) | ||
| 2 | Ascender in millipoints (16-bit signed) | ||
| 4 | reserved (must be zero) | ||
The kerning information is indexed by a hash table. The hash function used is:
(first letter) EOR (second letter ROR 4)
where the rotate happens in 8 bits.
| Size | Description |
|---|---|
| 256 × 4 | hash table giving offset from table start of first kern pair for each possible value (0 - 255) of hash function |
| 4 | offset of end of all kern pairs from table start |
| 4 | flag word:
|
| ? | kern pair data |
Each kern pair consists of the code of the first letter of the kern pair, followed by the x offset in millipoints (if flags bit 1 is clear) and the y offset in millipoints (if flags bit 2 is clear).
If bit 31 of the flag word is clear, then the letter code, x offset and y offset are each held in a word. If bit 31 is set, then the kern pair data is shortened by combining the letter code with the first offset word as follows:
bits 0 - 7 = character code
bits 8 - 31 = x or y offset
If necessary, the second letter can be deduced from the first letter and the hash index as follows:
2nd letter = (1st letter EOR hash table index) ROR 4
where the rotate happens in 8 bits.
The hash table indicates the point at which to start looking for a given kern pair in the list of kern pairs following the table. The entries are consecutive, so each list finishes as the next one starts. To search for a given kern pair:
Once the kern offsets are obtained, they can be inserted into a Font_Paint string as character 9 and 11 move sequences. (You can also paint kerned text using Font_Paint, which may be an easier option.)
Note that if flag bits 1 and 2 are both set, then it is illegal for there to be any kern pairs.
None
R0 = flags:
encoding menu, else font menu just return size) 0)
R0, R1 preserved
R2 = pointer to rest of menu selections (if R3 0 on entry)
R3 preserved
R4 = size of buffer required to hold output string (0 no font selected)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call decodes a selection (as returned from Wimp_Poll) made from a font menu. The definition of the font menu is passed in the same format as returned from Font_ListFonts.
This call is not available in RISC OS 2.
Bit 0 of R0 determines whether it is the font menu or the encoding menu that is being decoded. In either case, the format of the returned string depends on whether the names of the fonts/encodings have been specified in a Messagesn file inside the font directory. The name field is not present if the Font Manager has worked out the list of fonts/encodings by scanning the directory instead.
| File holds: | Format of returned string: | ||
|---|---|---|---|
| Font id, no name | \Ffont_id | ||
| Font id, with name | \Ffont_id\fterritory fontname | ||
| Encoding, no name | \Eencoding_id
| Encoding, with name
| \Eencoding_id\eterritory encoding_name
| |
Since Font_DecodeMenu works by comparing the string in the menu against the Font Manager's known font names, in the case of 'System font' being selected from a menu that contained it, R4 would be returned as 0. To distinguish this from the 'no font selected' case, check for R2 pointing to 0 on entry, since 'System font' is always the first menu entry if present.
R0 = initial font handle (1 - 255) or 0 for current handle - if bit 8 of R2 is set
R1 = pointer to string
R2 = plot type:
use R5 as indicated below use R6 as indicated below use R7 as indicated below use R0 as indicated above perform kerning on the string writing direction is right to left; else left to right return nearest caret position; else length of string return bounding box of string in buffer pointed to by R5 (bit 5 must be set) return matrix applying at end of string in buffer pointed to by R6 (bit 6 must be set) return number of split characters in R7 (bit 7 must be set)R0 preserved
R1 = pointer to point in string of caret position - if bit 17 of R2 is set; else to split point, or end of string if splitting not required
R2 preserved
R3, R4 = x, y coordinate offset to caret position - if bit 17 of R2 is set; else to split point, or end of string if splitting not required
R5, R6 preserved
R7 = number of split characters encountered - if bit 20 of R2 was set; else preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call scans a string as if it were painted to the screen using Font_Paint, and returns various information about it. It is particularly useful for finding the correct position of the caret within a string, or for finding where to split a line, if at all.
For full details of the parameters passed, and of control sequences that may be included in the string, you should see the description of Font_Paint on Font_Paint. Below we merely describe the changes and additions relative to that SWI.
This call is not available in RISC OS 2.
Unlike Font_Paint, this call uses millipoints for all coordinates; you may not specify OS units by setting bit 4 of R2.
R3 and R4 do not specify the start coordinates of the string. Instead they specify either the offset from the start of the string to the mouse click (used to work out where to insert the caret), or the maximum offset before the split point (ie the width and height remaining on the current line).
On exit R3 and R4 give the offset of the caret position or the split point. When scanning to determine the split point, the scan continues until the current offset is less than or greater than the limit supplied, depending on the sign of that limit. If R3 is negative on entry, the scan continues until the x offset is less than R3, while if R3 is positive, the scan continues until the x offset is greater than R3. Note that this is incompatible with the old Font_StringWidth call, which always continued until the x and y offsets were greater than R2 or R3. (Font_StringWidth still works in the old way, to ensure compatibility).
Font_ScanString does not use graphics cursor coordinates for justification, nor to specify a rubout box. Justification can still be performed using the coordinate block pointed to by R5, whereas rubout boxes are not supported at all.
The coordinate block pointed to by R5 differs from that used by Font_Paint in that no rubout box is given. Instead the word at offset 16 is used to specify the 'split character' on entry.
The four following words (ie starting at offset 20) are used to return the string's bounding box, if bit 18 of R2 is set on entry. This excludes the area occupied by underlining or rubout
| Offset | Value |
|---|---|
| 0 | additional x, y offset on space |
| 8 | additional x, y offset between each letter |
| 16 | split character (-1 none)
|
| 20 | returned x, y coordinates for bottom left of string bounding box (inclusive) - if bit 18 of R2 is set |
| 28 | returned x, y coordinates for top right of string bounding box (exclusive) - if bit 18 of R2 is set |
If there is no split character, but bit 20 of R2 is set ('return number of split characters in R7'), then R7 will instead be used to return the number of non-control characters encountered (ie those characters with codes of 32 or more which are not part of a control sequence).
If bit 19 of R2 is set on entry, the transformation matrix pointed to by R6 is updated on exit to return the matrix applying at the end of the string.
Where bit 10 is set (ie the main writing direction is right to left), one would normally supply a negative value of R3.
Note that the character at [R1,R7] may be accessed to determine whether it is a 'split character', as well as to determine the character offset due to kerning.
This SWI replaces the following deprecated (still supported, but not recommended) SWIs:
Font_StringWidth, Font_FindCaret, Font_FindCaretJ, Font_StringBBox
This call is for internal use by the ColourTrans module only. You must not use it in your own code.
This call is not available in RISC OS 2.
To set font colours you should either use ColourTrans_SetFontColours (see ColourTrans_SetFontColours) or Font_Paint control sequence 19 (see Changing colour).
--
R0 = font handle
R1 = background font colour (&BBGGRR00)
R2 = foreground font colour (&BBGGRR00)
R3 = maximum colour offset (0 mono, else anti-aliased)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call reads the settings of the RGB foreground and background colours after calling Font_Paint.
This call is not available in RISC OS 2.
The error 'Undefined RGB font colours' is generated if the colours were not set using RGB values.
None
None
Reads the settings of colours after calling various Font... SWIs
--
R0 = font handle
R1 = background font colour (&BBGGRR00)
R2 = foreground font colour (&BBGGRR00)
R3 = maximum colour offset (0 mono, else anti-aliased)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call reads the settings of the RGB foreground and background colours after calling Font_ScanString, Font_StringWidth, Font_StringBBox, Font_FindCaret or Font_FindCaretJ.
This call is not available in RISC OS 2.
The error 'Undefined RGB font colours' is generated if the colours were not set using RGB values.
None
Returns the filename of the encoding file used for a given font handle
R0 = font handle
R1 = pointer to buffer to receive prefix
R2 = length of buffer
R0 = pointer to encoding filename (in buffer)
R1 = pointer to terminating 0 of filename
R2 = bytes remaining in buffer
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call returns the filename of the encoding file used for a given font handle. It is primarily useful for PDriverPS to gain access to the file of identifiers that defines an encoding, in order to send it to the printer output stream.
The filename depends on whether the font has a 'public' or 'private' encoding (public encodings apply to 'language' fonts, as described in Font_ListFonts, while private encodings are not used by the Font Manager, and simply describe the PostScript names for the characters in the font).
| Encoding | Filename |
|---|---|
| public | font_prefix.Encodings.encoding |
| private | font_prefix.font_name.Encoding |
The error 'Buffer overflow' is generated if the buffer is too small.
This call is not available in RISC OS 2.
None
Returns a pointer to a specified field within a font identifier
R1 = pointer to font identifier
R2 = character code of qualifier required
R1= pointer to value following qualifier in string (if field present); else preserved
R2 = 0 if field not present; else preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call, given a font string and a qualifier that specifies a field within that string, returns a pointer to the specified field.
The 'F' field is space-terminated, while all others are control-character terminated.
This call is not available in RISC OS 2.
None
Merges a new set of fields with those already in a given font identifier
R0 = pointer to original font identifier
R1 = pointer to set of fields to be added (in format of a font identifier)
R2 = pointer to output buffer, or 0 to get required new size of buffer
R3 = size of output buffer
R0 - R2 preserved
R3 = remaining size of buffer, or incremented by the length of the output string (excluding its null terminator)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call merges a new set of fields with those already in a given font identifier, replacing existing fields and adding new ones. You can also delete existing fields by specifying a null field to replace it.
This operation is performed in two passes:
This call is not available in RISC OS 2.
R0 = font handle, or 0 for current handle
R1 = 0
R2 = 0
R0, R1 preserved
R2 = characteristics of font:
font is old 'x90y45' bitmap format font is in ROM font is monochrome only, irrespective of value of FontMax2 font is filled with non-zero rule, rather than even-oddInterrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call returns information about a particular font. On exit R2 contains a set of flags describing how the font is rendering, and other characteristics.
This call is not available in RISC OS 2, nor in RISC OS 3 (version 3.00).
None
Sets the configured maximum desirable size of the font cache
*Configure FontMax mK|n
mK - number of kilobytes of memory reserved
n - number of 4k chunks of memory reserved
*Configure FontMax sets the configured maximum desirable size of the font cache. The difference between FontSize and FontMax is the extra amount of memory that the Font Manager will attempt to use if it needs to. If other parts of the system have already claimed all the spare memory, then FontSize is what it is forced to work with.
If FontMax is bigger than FontSize, when the Font Manager cannot obtain enough cache memory it will attempt to expand the cache by throwing away unused blocks (ie ones that belong to fonts which have had Font_FindFont called on them more often than Font_LoseFont). Once the cache has expanded up to FontMax, the Font Manager will throw away the oldest block found, even if it is in use. This can result in the Font Manager heavily using the filing system, since during a window redraw it is possible that all fonts will have to be thrown away and recached in turn.
The Font Manager has to keep permanently in its cache some information on each font in use. Consequently, if many more fonts are in use than are reasonable for the configured FontMax, the Font Manager may be forced to let the cache grow past this point.
*Configure FontMax 256K
*Configure FontSize
Sets the maximum height at which to scale from a bitmap font
*Configure FontMax1 max_pointsize
max_height - maximum height of font at which to scale from a bitmap font; units are points, except under RISC OS 2, which uses pixel height (see below)
*Configure FontMax1 sets the maximum height at which to scale from a bitmap font rather than from an outline font - but only if 4 bit per pixel output is possible.
When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size; then it looks for an x90y45 font of the correct size. Next it considers the values of FontMax2 and 3, and then of FontMax4 and 5. Only if the above fail to produce output does it then consider the value of FontMax1:
The height is set in points, except under RISC OS 2 which uses pixel height:
pixel height = height in points × pixels (or dots) per inch / 72
The pixel height corresponds to different point sizes on different resolution output devices.
*Configure FontMax1 25
*Configure FontMax2
Sets the maximum height at which to scale from outlines to anti-aliased bitmaps
*Configure FontMax2 max_height
max_height - maximum height of font at which to scale from outlines to anti-aliased bitmaps; units are points, except under RISC OS 2, which uses pixel height (see below)
*Configure FontMax2 sets the maximum height at which to scale from outlines to anti-aliased bitmaps, rather than to 1 bit per pixel bitmaps.
When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size; then it looks for an x90y45 font of the correct size. Only if the above fail to produce output does it then consider the value of FontMax2:
If it fails to find one it uses the Outlines file to paint a 1 bit per pixel bitmap. The value of FontMax3 determines whether the Font Manager caches the bitmap or the outline.
The height is set in points, except under RISC OS 2 which uses pixel height:
pixel height = height in points × pixels (or dots) per inch / 72
The pixel height corresponds to different point sizes on different resolution output devices.
*Configure FontMax2 20
*Configure FontMax1, *Configure FontMax3
Sets the maximum height at which to retain bitmaps in the cache
*Configure FontMax3 max_height
max_height - maximum height of font at which to retain bitmaps in the cache; units are points, except under RISC OS 2, which uses pixel height (see below)
*Configure FontMax3 sets the maximum height at which to retain bitmaps in the cache, rather than the outlines from which they were converted.
Unlike the other FontMaxn values, FontMax3 affects the Font Manager both when it can use 4 bits per pixel, and when it can only use 1 bit per pixel.
When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size; then it looks for an x90y45 font of the correct size. Only if the above fail to produce output does it then consider the value of FontMax3:
Otherwise, the Font Manager first looks for a b9999x9999 file of the correct size.
If it fails to find one it uses the Outlined file to paint a 1 bit per pixel bitmap. The value of FontMax3 determines whether the Font Manager caches the bitmap or the outline:
It draws the outlines directly onto the destination using the Draw module; consequently they are not anti-aliased. The Font Manager sets up the appropriate GCOL and TINT settings for this, and resets them afterwards.
If the Font Manager can only use 1 bit per pixel, it first looks for a b9999x9999 file of the correct size.
If it fails to find one it looks for the Outlines file, scaling it to give a 1 bit per pixel bitmap. The value of FontMax3 determines whether the Font Manager caches the bitmap or the outline:
It draws the outlines directly onto the destination using the Draw module; consequently they are not anti-aliased. The Font Manager sets up the appropriate GCOL and TINT settings for this, and resets them afterwards.
If there is no Outlines file, the Font Manager then looks for an f9999x9999 file of the correct size; then it looks for an x90y45 font of the correct size. Finally it uses the x90y45 file to determine which bitmap font to scale. If the x90y45 file contains the name of an f9999x9999 file, then that file is scaled; else one of the fonts in the x90y45 file is scaled.
The height is set in points, except under RISC OS 2 which uses pixel height:
pixel height = height in points × pixels (or dots) per inch / 72
The pixel height corresponds to different point sizes on different resolution output devices.
*Configure FontMax3 35
*Configure FontMax2
Sets the maximum width at which to use horizontal subpixel anti-aliasing
*Configure FontMax4 max_width
max_width - maximum width of font at which to use horizontal subpixel anti-aliasing; units are points, except under RISC OS 2, which uses pixel width (see below)
*Configure FontMax4 sets the maximum width at which to use horizontal subpixel anti-aliasing.
When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size (note that this bitmap may have been constructed with subpixel anti-aliasing already performed - see Font_MakeBitmap); then it looks for an x90y45 font of the correct size. Next it considers the values of FontMax2 and 3. Only if the above fail to produce output does it then consider the value of FontMax4 and 5:
Likewise, if the font pixel wheight is less than or equal to the height specified in FontMax5, the Font Manager will perform vertical subpixel anti-aliaing. Thus if both horizontal and vertical subpixel anti-aliasing occurs, 16 bitmaps will be constructed.
When painting the text, the Font Manager will use the bitmap which corresponds most closely the the required alignment.
The width is set in points, except under RISC OS 2 which uses pixel width:
pixel height = height in points × pixels (or dots) per inch / 72
The pixel width corresponds to different point sizes on different resolution output devices.
*Configure FontMax4 0
*Configure FontMax5
None
Sets the maximum height at which to use vertical subpixel anti-aliasing
*Configure FontMax5 max_height
max_height - maximum font pixel height at which to use vertical subpixel anti-aliasing
*Configure FontMax5 sets the maximum height at which to use vertical subpixel anti-aliasing.
When the Font Manager can use 4 bits per pixel, it first looks for an f9999x9999 file of the correct size (note that this bitmap may have been constructed with subpixel anti-aliasing already performed - see Font_MakeBitmap); then it looks for an x90y45 font of the correct size. Next it considers the values of FontMax2 and 3. Only if the above fail to produce output does it then consider the value of FontMax4 and 5:
Likewise, if the font pixel wheight is less than or equal to the height specified in FontMax5, the Font Manager will perform horizontal subpixel anti-aliaing. Thus if both horizontal and vertical subpixel anti-aliasing occurs, 16 bitmaps will be constructed.
When painting the text, the Font Manager will use the bitmap which corresponds most closely the the required alignment.
The height is set in points, except under RISC OS 2 which uses pixel height:
pixel height = height in points × pixels (or dots) per inch / 72
The pixel height corresponds to different point sizes on different resolution output devices.
*Configure FontMax4 0
*Configure FontMax5
Sets the configured amount of memory reserved for the font cache
*Configure FontSize sizeK
size - number of kilobytes to allocate
*Configure FontSize sets the configured amount of memory reserved for the font cache. This is claimed when the Font Manager is first initialised. If insufficient memory is free, the Font Manager starts running using what is available.
The Font Manager will never shrink its cache below this configured size.
The minimum cache size can also be changed from the Task Manager, by dragging the font cache bar directly, although this is not remembered after a Control-reset.
*Configure FontSize 32K
*Configure FontMax
None
*FontCat [directory]
directory - pathname of a directory to search for fonts
*FontCat lists the fonts available in the given directory. If no directory is given, then the directory specified in the system variable Font$Path is used.
Font_FindFont uses the same variable when it searches for a font.
*FontCat ADFS:$.Fonts. The last '.' is essential Corpus.Medium Portrhouse.Standard Trinity.Medium
None
None
*FontInstall [directory]
directory - pathname of a directory to add to Font$Path
*FontInstall adds a directory to the list of those scanned for fonts. It does so by altering the system variable Font$Path so that the given pathname appears before any others, and is not repeated. It also rescans the directory, even if it was already known to the Font Manager.
If no pathname is given, all directories in Font$Path are rescanned.
FontInstall will only rescan a directory already on the path if it moves to the head of the path. The best way to force a re-scan after changing a directory known to the Font Manager is to call *FontRemvoe, then *FontInstall.
Service_FontsChanged is issued whenever a directory is scanned.
This command is not available in RISC OS 2.
*FontInstall RAM:$.Fonts. The last '.' is essential
*FontRemove
None
None
Sets a directory as the font library, replacing the previous library
*FontLibrary directory
directory - a valid pathname specifying a directory
*FontLibrary sets a directory as the font library, replacing the previous library in the list of those scanned for fonts. It does so by altering the system variable Font$Prefix to the given directory, and ensures that the string '<Font$Prefix>.' appears on the front of the system variable Font$Path.
Note however that if the previous font library had also been explicitly added to Font$Path (say by *FontInstall), it will still be scanned.
This command is not available in RISC OS 2.
*FontLibrary SCSIFS::MyDisc.$.FontLib
None
None
Displays the fonts in the font cache, its size, and its free space
*FontList
None
*FontList displays the fonts currently in the font cache. For each font, its identifier is given, together with its point size, its resolution, the number of times it is being used by various applications, and the amount of memory it is using.
The size of the font cache and the amount of free space (in Kbytes) is also given.
*FontList
Name Size Dots/inch Use Cache memory
---- ---- --------- --- ------------
1.Homerton.Medium 12 point 90x45 3 4 Kbytes
2.Homerton.Medium master ROM outlines 1 696 bytes
Cache size: 32 Kbytes
free: 24 Kbytes
None
None
Removes a directory from the list of those scanned for fonts
*FontRemove [directory]
directory - pathname of a directory to remove from Font$Path
*FontRemove removes a directory from the list of those scanned for fonts. It does so by removing the given pathname from the system variable Font$Path.
This command is not available in RISC OS 2.
*FontRemove RAM:$.Fonts. The last '.' is essential
*FontInstall
None
None
*LoadFontCache filename
filename - a valid pathname specifying a file previously saved using *SaveFontCache
*LoadFontCache loads a file that was previously saved using *SaveFontCache back into the font cache.
An error is generated if any fonts are currently claimed, or if the font cache format cannot be read by the current Font Manager (ie it was created by a version of the Font Manager that used an incompatible font cache format).
The size of the font cache slot will - if necessary - be increased to accommodate the new cache data; but it will not be decreased, even if the new cache data is smaller than the current cache slot size.
This command is useful for setting up the font cache to a predefined state, to save time scaling fonts later on.
Note: A saved font cache is only valid if RMA usage is the same as when it was saved, since it contains absolute pointers into modules and their workspace. If RMA usage has altered (eg the cache is loaded to a different address, or the Font Manager's workspace is in a different location) you will get no error on loading the cache; but you will get many subsequent errors. This call (and SaveFontCache) is therefore deprecated.
This command is not available in RISC OS 2.
*LoadFontCache SCSIFS::MyDisc.$.FontCache
*SaveFontCache
None
None
*SaveFontCache filename
filename - a valid pathname specifying a file
*SaveFontCache saves the current contents of the font cache, with certain extra header information, to a file of type &FCF (FontCache). The Run alias for this filetype executes *LoadFontCache, which loads the file back into the font cache.
Note: A saved font cache is only valid if RMA usage is the same as when it was saved, since it contains absolute pointers into modules and their workspace. If RMA usage has altered (eg the cache is loaded to a different address, or the Font Manager's workspace is in a different location) you will get no error on loading the cache; but you will get many subsequent errors. This call (and LoadFontCache) is therefore deprecated.
This command is not available in RISC OS 2.
*SaveFontCache SCSIFS::MyDisc.$.FontCache
*LoadFontCache
None
None
100 SYS "Font_FindFont",,"Trinity.Medium",320,320,0,0 TO HAN% 110 REM sets font handle 120 SYS "Font_SetPalette",,8,9,6,&FFFFFF00,&00000000 130 REM Set the palette to use colours 8-15 as white to black 140 MOVE 800,500 150 REM Set the right hand side of justification 160 SYS "Font_Paint",,"This is a test",&11,0,500 170 SYS "Font_LoseFont",HAN%
On line 160, Font_Paint is being told to use OS coordinates and justify, starting at location 0,500. 800,500 has been declared as the right hand side of justification by line 140.