`phfont`

Photon font server

Syntax:

phfont [-A] [-b file]
       [-C[-]SANSERIF|SERIF|DECORATIVE=description[;description2[;...]]]
       [-D directory]
       [-d directory] [-E rule]
       [-F types] [-e file] [-I] [-i file]
       [-K[-]FONDRY|AFTERFOUNDRYKEYS|KEYS=key[;key2[;...]]]
       [-L] [-l list]
       [-mPHF|PFR|TTF=newname[=realname][;newname2=[realname2][;...]]]
       [-N number]
       [-O[-]keyword[;[-]keyword2[;...]]]
       [-n name] [-s directory]
       [-U family] [-u file]
       [-X] [-Z alignment]

Options:

-A

Force all text bitmaps to be anti-aliased wherever possible. Only scalable fonts can be anti-aliased.

-b file

Save font usage information to the specified file when phfont exits.

-C[-]SANSERIF|SERIF|DECORATIVE=description[;description2[;...]]

Manage the font classification list. Font classification lists are used to return correct information to the user's application when fonts (such as PHF fonts) don't contain classification information in them.

This option is used to add or remove a description to or from a font class. Use the - preceding the font class name to remove descriptions. This option could be used more than once on the command-line.

-D directory

Specify the configuration directory that holds the fontdir, fontext, fontmap, and fontopts files. The default is /usr/photon/font_repository.

-d directory

Specify the font directory. All configuration files and font files are assumed to be in this directory. The default is /usr/photon/font_repository.

-E rule

Specify the extension/dropout rule to use. The fontext file may contain a number of different extension rules (e.g. language rules that search the Chinese, Japanese, or Korean character set) of which only one is active. By default, the first “+” rule in the fontext file is used.

-e file

Specify the font extension/dropout file. This file contains rules that extend a base output character set to include multiple font files (e.g. to add special symbols or languages other than English). The default file is fontext.

-F types

Print the defaults for the specified types and exit, where types is a string containing one or more of:

C — font classes
K — font keys
O — oriental keywords
m — font mappings

-I

Use strict international mapping rules.

-i file

Specify the font index file. This file contains header information of every known/usable font in the system and allows the font server to quickly perform font mappings and character dropouts without accessing the disk. The default file is fontdir.

-K[-]FONDRY|AFTERFOUNDRYKEYS|KEYS=key[;key2[;...]]

Font Keys are removed from the font description from the specific location within description.

If - is used, the specified keys are removed from the specified key location. This option could be used more than once.

-L

Deny local metrics loading.

-l list

Specify a list of fonts to preload and lock into cache. You can use this to ensure fast access to common fonts. The list is formatted as a comma-separated list of font names. For example:

helv10,phcursor,cour10b,swissi

Default is none.

-M

Disable the display of missing-character symbols. By default, whenever a character is rendered for which no definition can be found, the font server displays an empty rectangle.

-mPHF|PFR|TTF=newname[=realname][;newname2=[realname2][;...]]

For internal use only. Entries in this file override the descriptive name (for example, Helvetica) for a particular font stem (helv). This option adds a new mapping to the specified font type list. If realname is not provided, this newname is removed from the specified font type list. This option can be used more than once on the command-line.

-N number

Specify the number of times the font manager tries to attach a device before exiting.

Default is 15.

-n name

Specify the name to register the font server with. By default the value of the PHFONT environment variable is used; if this isn't set, the prefix /dev/phfont is used.

-O[-]keyword[;[-]keyword2[;...]]

Manage oriental keywords. Keywords used to identify Asian (Oriental) font foundry names, and are used to optimize the extension system.

If a keyword starts with a -, this keyword is removed from the list, otherwise it is added to the list. This option can be used more than once on the command-line.

-s dir

Directory containing font engines . By default this is /lib/dll/font.

-U family

Specify the font family to use for unknown fonts. Whenever a named font doesn't exist and can't be resolved by explicit mapping entries, this default font family is used. By default the ? entry in the fontmap file is used.

-u file

Specify the unknown font-mapping table file. This file creates font synonyms (or virtual fonts) and configuration rules for augmenting bitmap fonts with scalable fonts. The default file is fontmap.

-X

Prevent the font server from terminating after the last client disconnects. The default is for the font server to exit once all clients have terminated.

-Z alignment

Set the bitmap alignment to 8, 32, or 64 bit. This is used in DLL mode only. See PfSetOptionsDll().

You can pass options through the -F option to io-graphics when you aren't running an external font server. The format is slightly different, based on the getsubopt() format. For example:

io-graphics -F"-d=/usr/photon/font_repository,-A,-N=10" ...

See PfSetOptionsDll() for more information.

Description:

The phfont utility provides all font services to Photon applications and drivers. This includes the calculation of text extents and metrics and the generation of bitmaps representing character strings. It also maintains a central cache of font metric and bitmap data. The configuration files used by phfont are described in Files below.

When phfont is being initialized, it pre-processes the command line to find out which configuration directory to use, then it tries to load the $HOME/.ph/font/fontopts file. If this file doesn't exist, it tries to load the config_dir/fontopts file. It tries to load the [io-font] and then it tries to load the [io-font-server] sections. The options from the loaded sections are combined with the options from the command line and then processed, with the options in the command line taking higher precedence in the case of conflicts. The options in the [io-font] section of the fontopts file are used by all applications that load phfont.so. When using PfAttachLocalDll, the option name is used to try to load the [io-font-option_name] section from the fontopts file too.

This utility needs to have the setuid (“set user ID”) bit set in its permissions. If you use mkefs, mketfs, or mkifs on a Windows host to include this utility in an image, use the perms attribute to specify its permissions explicitly, and the uid and gid attributes to set the ownership correctly.

The phfont utility loads the phfont.so DLL to provide font rendering services. The phfont.so loads DLLs located in /lib/dll/font which provide rendering services for specific font types, such as PHF, TTF, TTC, PFR, Stroke, etc.

If a particular type of rendering is not desired, you can remove the specific dll. To determine which services are provided by each DLL, use the use dll_name command, which displays the usage message for that particular DLL. If an external font server is not started, io-graphics attempts to invoke a font server instance.

The phfont server can run as a stand alone process (we refer to this as an external server) or as a plugin to io-graphics (which we call an internal server). We recommend you run an external server in these conditions:

Your system will not run io-graphics.
Your system will be used as a server for remote photon sessions.

To run an external font server, start phfont before io-graphics. To run an internal font server, simply start io-graphics.

Examples:

Start the server:

phfont -d /usr/photon/font_repository &

Normally the font server is started from the ph script.

Files:

The rendering DLLs used by the font server are located in /lib/dll/font/*.so. These files support rendering for at least these font types:

TrueType
TrueType collections
Bitstream TrueDoc PFR
Photon Bitmap
Bitstream Stroke
Bitstream Speedo
Bitstream T2K
Adobe Type1
Adobe Type2

Use the use command to view the font types supported by a DLL.

Other files used by phfont include:

fontdir — directory of known fonts
fontext — extension rules to handle missing characters
fontmap — font mapping rules
fontopts — command-line options

These files were used by previous versions of phfont, but are now deprecated:

fontdesc — use the -C option instead.
font-traplist
fontdynamic
fontkey — use the -K option instead.
fontopt
fontorient — use the -O option instead.
fontpreferred
mappings — use the -m option instead.

`fontdir`

Directory of known fonts — required. Each entry in this file contains information such as the name and type of the font, its size and style, a textual description of the font family, and the range of characters defined within the font. To be available to an application, at least one font must be defined in this configuration file. Entries in this file are static, they can't be loaded dynamically.

Each line in this file contains the following comma-separated fields, in this order, for each known font:

stem name
font type/location — for phf files, this is simply the string to add to the stem name to get the filename containing the font. For others, this is in the form index@filename, where index is the index into the font contained in filename. This value is always 0.
textual description, i.e. PC Serif
point size, i.e. 8
Font style, i.e. B if bold, I if italics, or a combination
range of characters defined within font, i.e. 0000-00FF
special (internal) flags
font bounding size, i.e. 8x8
font size in K, i.e. 12K

`fontext`

A set of extension rules to handle character dropouts (missing characters) — required. The format of this file is as follows:

+type = fontname [,fontname...]

Where type is the font type (normal, bold, etc.) and fontname is the font name to search for symbols.

`fontmap`

A set of mapping rules — required. There are two types:

Synonym entries, that have the form:
```
newfont = realfont
            
```
In this mapping rule, newfont doesn't exist, but realfont does. If you try to use newfont as a font name, it's mapped to realfont.
The following special-case entry is a default mapping for any unknown font name:
```
? = realfont
            
```
For example, if geneva = helv, then the font geneva12 is translated to helv12.

Scaling entries, that have the form:

font = {when}scalefont

In this mapping rule, both font and scalefont must exist. When there isn't an exact PHF file for font, then a scaled version of scalefont is made according to the when character used:

*: Always scale when no exact PHF file exists for font.
+: Scale only when above the largest size PHF defined for font.
-: Scale only when below the smallest size PHF defined for font.
#: Scale when outside the range of sizes of PHF files for font

For example, if the files helv08.phf, helv10.phf, and helv12.phf are present and swiss is a scalable font, the following translations are made:

Rule	Input font	Translated font
`helv = *swiss`	`helv06`	`swiss06`
	`helv11`	`swiss11`
	`helv23`	`swiss23`
`helv = -swiss`	`helv06`	`swiss06`
	`helv11`	`helv10`
	`helv23`	`helv12`
`helv = +swiss`	`helv06`	Missing-symbol box
	`helv11`	`helv10`
	`helv23`	`swiss23`
`helv = #swiss`	`helv06`	`swiss06`
	`helv11`	`helv10`
	`helv23`	`swiss23`

In all cases, the fonts helv08, helv10, and helv12 (known valid fonts) are used directly.

`fontopts`

Contains the command-line options, one option per line — optional. Options are located under the appropriate schema section. For example, phfont-specific options are located in the [io-font] section. Options targeted towards a specific rendering DLL are divided into subsections: boolean, numeral, string. They are formatted as follows:

    [dll id-subsection-schema]

The font server may run in one of two modes: server mode, or private client DLL mode. In order to differentiate options between the two, by default there is a "dll" schema. If the font server is running in server mode, it searches for options under [dll id-subsection], but if the font server is running in client DLL mode, it searches for options under [dll id-subsection-dll]. If no options are specified, the default values are used.

Environment variables:

PHFONT: The default name with which to register the font server.

phfont