Setting Character Attributes

Plplot uses two separate font systems to display characters. The traditional system uses Hershey fonts which are available for all device drivers, while the recently introduced unicode system is currently available only for the ps, psc, png, jpeg, and gif devices. For details on how to enable the unicode font system for additional device drivers using the FreeType library, see the section called “Adding FreeType Library Support to Bitmap Drivers”.

Hershey fonts

There are two Hershey font character sets included with PLplot. These are known as the standard and extended character sets. The standard character set is a subset of the extended set. It contains 177 characters including the ascii characters in a normal style font, the Greek alphabet and several plotter symbols. The extended character set contains almost 1000 characters, including four font styles, and several math, musical and plotter symbols.

The extended character set is loaded into memory automatically when plstar or plstart is called. The standard character set is loaded by calling plfontld. The extended character set requires about 50 KBytes of memory, versus about 5 KBytes for the standard set. plfontld can be used to switch between the extended and standard sets (one set is unloaded before the next is loaded). plfontld can be called before plstar.

When the extended character set is loaded there are four different font styles to choose from. In this case, the routine plfont sets up the default Hershey font for all character strings. It may be overridden for any portion of a string by using an escape sequence within the text, as described below. This routine has no effect when the standard font set is loaded. The default font (1) is simple and fastest to draw; the others are useful for presentation plots on a high-resolution device.

The font codes are interpreted as follows:

  • font = 1: normal (sans-serif) font

  • font = 2: roman (serif) font

  • font = 3: italic font

  • font = 4: script font

Unicode fonts

The advantages of the unicode fonts over the more traditional PLplot Hershey fonts are the availability of many additional glyphs (including mathematical symbols and glyphs from other than western-European languages) and much better display of characters on computer screens using anti-aliasing and hinting. Unicode fonts are obtained by specifying a command-line option of -drvopt text for the devices (currently ps, psc, png, jpeg, gif, and wingcc) where it has been implemented.

For the ps and psc devices, there is a fixed relationship between the FCI (font characterization integer, see the section called “FCI”) and the actual Type 1 fonts that are being used. This fixed relationship is specified in the Type1Lookup array in include/plfci.h. This array maps the font-family attributes of sans-serif, serif, monotype, script, and symbol to the standard postscript font families called Helvetica, Times-Roman, Courier, Times-Roman, and Symbol. (There is no script font family amongst the 35 standard Type 1 postscript fonts so that is why we map the font-family attribute of script to Times-Roman.) Similarly, this array maps the font-style attributes of upright, italic or oblique and the font-weight attributes of medium or bold to the appropriate variety of the Helvetica, Times-Roman, Courier, and Symbol font families that are part of the 35 standard Type 1 postscript fonts. These standard postscript fonts are normally installed on a user's system using the gsfonts package.

For the devices handled by the FreeType library (currently png, jpeg, and gif) there is a configurable relationship between the FCI (font characterization integer, see the section called “FCI”) and the TrueType fonts that are actually used.

The TrueType fonts corresponding to the 30 possible valid FCIs can be specified using cmake options. The defaults for the 30 cmake variables PL_FREETYPE_FONT[_MODIFIER] (where FONT is one of MONO, SANS, SCRIPT, SERIF or SYMBOL and the optional MODIFIER is one of BOLD, BOLD_ITALIC, BOLD_OBLIQUE, ITALIC or OBLIQUE) are documented in cmake/modules/freetype.cmake. On Windows these defaults use standard Windows fonts. On all other platforms defaults are taken from fonts available from the ttf-freefont font package. We recommend this font package because it has a rather complete set of glyphs for most unicode blocks. (We also recommend the gucharmap application for determining other unicode font possibilities on your system that are available via the FreeType library.)

For all systems, the 30 possible TrueType fonts can be specified at run time using the following environment variables:

  • PLPLOT_FREETYPE_SANS_FONT

  • PLPLOT_FREETYPE_SERIF_FONT

  • PLPLOT_FREETYPE_MONO_FONT

  • PLPLOT_FREETYPE_SCRIPT_FONT

  • PLPLOT_FREETYPE_SYMBOL_FONT

  • PLPLOT_FREETYPE_SANS_ITALIC_FONT

  • PLPLOT_FREETYPE_SERIF_ITALIC_FONT

  • PLPLOT_FREETYPE_MONO_ITALIC_FONT

  • PLPLOT_FREETYPE_SCRIPT_ITALIC_FONT

  • PLPLOT_FREETYPE_SYMBOL_ITALIC_FONT

  • PLPLOT_FREETYPE_SANS_OBLIQUE_FONT

  • PLPLOT_FREETYPE_SERIF_OBLIQUE_FONT

  • PLPLOT_FREETYPE_MONO_OBLIQUE_FONT

  • PLPLOT_FREETYPE_SCRIPT_OBLIQUE_FONT

  • PLPLOT_FREETYPE_SYMBOL_OBLIQUE_FONT

  • PLPLOT_FREETYPE_SANS_BOLD_FONT

  • PLPLOT_FREETYPE_SERIF_BOLD_FONT

  • PLPLOT_FREETYPE_MONO_BOLD_FONT

  • PLPLOT_FREETYPE_SCRIPT_BOLD_FONT

  • PLPLOT_FREETYPE_SYMBOL_BOLD_FONT

  • PLPLOT_FREETYPE_SANS_BOLD_ITALIC_FONT

  • PLPLOT_FREETYPE_SERIF_BOLD_ITALIC_FONT

  • PLPLOT_FREETYPE_MONO_BOLD_ITALIC_FONT

  • PLPLOT_FREETYPE_SCRIPT_BOLD_ITALIC_FONT

  • PLPLOT_FREETYPE_SYMBOL_BOLD_ITALIC_FONT

  • PLPLOT_FREETYPE_SANS_BOLD_OBLIQUE_FONT

  • PLPLOT_FREETYPE_SERIF_BOLD_OBLIQUE_FONT

  • PLPLOT_FREETYPE_MONO_BOLD_OBLIQUE_FONT

  • PLPLOT_FREETYPE_SCRIPT_BOLD_OBLIQUE_FONT

  • PLPLOT_FREETYPE_SYMBOL_BOLD_OBLIQUE_FONT

On Unix/Linux systems if these environment variables are not specified with an absolute path starting with "/", then the absolute path is specified by the cmake variable PL_FREETYPE_FONT_PATH or at run time with the environment variable PLPLOT_FREETYPE_FONT_DIR.

FCI

We specify the properties of unicode fonts with the FCI (font characterization integer). The FCI is a 32-bit unsigned integer whose most significant hexadecimal digit is marked with an 0x8 (0x80000000 is ORed with the FCI value to mark it) to distinguish it from a unicode (UCS4) integer (whose maximum value 0x7fffffff). Users obtain the current FCI by calling plgfci and store a new FCI to be used at the start of each subsequent string using plsfci. Independent hexadecimal values within the FCI are characterized by the hexdigit and hexpower. The hexpower is defined as the power of 16 or number of hexadecimal places to the left of the "decimal place" in the FCI where the hexdigit is stored. The interpretation of the hexdigit and hexpower values in the FCI are given in Table 3.3, “FCI interpretation”.

Table 3.3. FCI interpretation

 hexdigit -->01234
Font attributehexpower     
font-family0sans-serifserifmonospacescriptsymbol
font-style1uprightitalicoblique  
font-weight2mediumbold   

Note the maximum value of hexdigit is 7 and the maximum value of hexpower is 6 so there is substantial room for expansion of this scheme. On the other hand, since each font attribute is independent of the rest, what is implemented now gives us a maximum of 30 different font possibilities which is probably more than enough for most plotting purposes.

Escape sequences in text

The routines which draw text all allow you to include escape sequences in the text to be plotted. These are character sequences that are interpreted as instructions to change fonts, draw superscripts and subscripts, draw non-ASCII (e.g. Greek), and so on. All escape sequences start with a number symbol (#) by default. Some language interfaces have the capability of changing this default, but we will assume (#) in the remaining documentation of the escape sequences.

The following escape sequences are defined:

  • #u: move up to the superscript position (ended with #d)

  • #d: move down to subscript position (ended with #u)

  • #b: backspace (to allow overprinting)

  • ##: number symbol

  • #+: toggle overline mode

  • #-: toggle underline mode

  • #gx: Greek letter corresponding to Roman letter x (see below)

  • #fn: switch to normal (sans-serif) font

  • #fr: switch to Roman (serif) font

  • #fi: switch to italic font

  • #fs: switch to script font

  • #(nnn): Hershey character nnn (1 to 4 decimal digits)

  • #[nnn]: unicode character nnn (nnn can be decimal or hexadecimal [e.g., starting with 0x]) (UNICODE ONLY).

  • #<0x8nnnnnnn>: absolute FCI to be used to change fonts in mid-string. (nnnnnnn must be exactly 7 digits). (UNICODE ONLY).

  • #<0xmn>: change just one attribute of the FCI in mid-string where m is the hexdigit and n is the hexpower. If more than two digits are given (so long as the eighth digit does not mark this as an absolute FCI, see above) they are ignored. (UNICODE ONLY).

  • #<FCI COMMAND STRING/>: the FCI COMMAND STRING is currently one of "sans-serif", "serif", "monospace", "script", "symbol", "upright", "italic", "oblique" "medium", or "bold" (without the surrounding quotes). These FCI COMMAND STRINGS change one attribute of the FCI according to their name. (UNICODE ONLY).

Sections of text can have an underline or overline appended. For example, the string S̅(f̲r̲e̲q̲) is obtained by specifying "#+S#+(#-freq#-)".

Greek letters are obtained by #g followed by a Roman letter. Table 3.4, “Roman Characters Corresponding to Greek Characters” shows how these letters map into Greek characters.

Table 3.4. Roman Characters Corresponding to Greek Characters

RomanABGDEZYHIKLM
GreekΑΒΓΔΕΖΗΘΙΚΛΜ
RomanNCOPRSTUFXQW
GreekΝΞΟΠΡΣΤΥΦΧΨΩ
Romanabgdezyhiklm
Greekαβγδεζηθικλμ
Romanncoprstufxqw
Greekνξοπρστυφχψω

The escape sequences #fn, #fr, #fi, #fs, and #(nnn) are designed for the four Hershey fonts, but an effort has been made to allow some limited forward compatibility so these escape sequences have a reasonable result when unicode fonts are being used. However, for maximum flexibility when using unicode fonts, these 5 escape sequences should be replaced by using the 4 escape sequences #[nnn], #<0x8nnnnnnn>, #<0xmn>, or #<FCI COMMAND STRING/> as appropriate.

It should be emphasized that the unicode escape sequences above only work properly for modern unicode-aware devices such as the svg device or the very large set of cairo and qt devices. And for those devices the alternative of simply specifying the unicode symbols using UTF-8 encoding of PLplot input strings is much more convenient for users than using the above escape sequences. For example, we use UTF-8 strings rather than escape sequences in example 24 to render the word "Peace" in several different languages.

Table 3.5. The word "peace" expressed in several different languages in example 24 using UTF-8

Hebrewשלום
FrenchPaix
KurdishHasîtî
EnglishPeace
Korean평화
TurkishBarış
Hindiशांति
GermanFriede
Arabicﺳﻼم
Mandarin和平
RussianМир
SpanishPaz

For unicode-aware devices it is possible as well to specify mathematical glyphs (such as ∂, ∇, ∑, ∫, and ∰) using UTF-8 encoding of PLplot input strings. A typical input method in this case is simply to cut and paste the desired mathematical glyph from, e.g., gucharmap to source code being edited by a unicode-aware editor such as emacs. Such input methods may be conveniently used, for example, to specify the very wide range of mathematical symbols that are typically desired for scentific plots.

Character size adjustment

The routine plschr is used to set up the size of subsequent characters drawn. The actual height of a character is the product of the default character size and a scaling factor. If no call is made to plschr, the default character size is set up depending on the number of subpages defined in the call to plstar or plstart, and the scale is set to 1.0. Under normal circumstances, it is recommended that the user does not alter the default height, but simply use the scale parameter. This can be done by calling plschr with def = 0.0 and scale set to the desired multiple of the default height. If the default height is to be changed, def is set to the new default height in millimeters, and the new character height is again set to def multiplied by scale.

The routine plssym sets up the size of all subsequent characters drawn by calls to plpoin and plsym. It operates analogously to plschr as described above.