SclGraphicsSetTextFont

Overview

Set the text characteristics so that the font and size of text can be controlled.

Synopsis

SclGraphicsSetTextFont fontSpecification

Arguments

fontSpecification

A Text Font specification is passed to the system as an arbitrarily long formatted string containing one or more options separated from each other by commas. Some of the options, as noted below, can be preceded by the word "no". Uppercase versus lowercase is not significant, nor are any leading or trailing blanks on any option. Embedded blanks within the option name itself are significant.

Each individual Text Font option inherits up and down the node tree and is set independently of all the other choices. You might find yourself calling SclGraphicsSetTextFont several times in a row, feeding in more choices each time. The new choices are merged in with the old as they arrive.

The following choices are recognized:

name = value

The name is commonly the most important part of a text font specification. The value is, in general terms, an arbitrary string of characters. If value happens to equal one of the recognized "generic" names, the selection of fonts that are available on your display will be searched and try to pick one that is that style (and of the necessary size).

The "generic" font names are

roman : Any font similar to the fonts used in most newspapers.
sans serif : A font similar to roman, but with the letters as plain and unadorned as possible.
typewriter : A font similar to those traditionally used in typewriters. Each character is equally wide when printed out.
stroked : A font that is drawn as a sequence of polylines.
system default : Whichever font the operating system or window manager says is the preferred default for your machine.
Newfield : A simplex monospace stroked roman font.
Enfield : A simplex variable-space stroked roman font similar to Newfield.
Brooktondale : A duplex variable-space stroked roman font.

If value is not one of above, it will be assumed to be the operating-system-recognized name of either a particular font that is available on your display, or a user defined font. Depending on how your system names fonts you might have to include a directory path in the value. If there are any special characters, value should be enclosed in either single or double quotes.

The "stroked" font is always available, and if no named font can be found the "stroked" font is used. (The "stroked" font is currently set to point to Enfield.) The default font name is "sans serif".

size = size-spec

The size gives guidance on how big the characters ought to be, specifically what the height of the characters ought to be, not including descenders ("descenders" are the tails on lowercase letters such as p and q).

Size-spec is a floating-point number followed by zero or more blanks followed by a "units specifier". The units specifier can be any of the following:

oru - "Object relative units". The number indicates text size in object space. This allows for fully transformable text, which is sized the same as most of the other geometries.
sru - "Subscreen relative units". The number indicates the fraction of the height of the outermost window (either the subscreen, if any, else the whole screen) that the characters ought to be. The picture is always internally the same, no matter how big the actual screen is. If there is a window manager, as the user changes the window size the characters scale to fit.
"0.03 sru" gives a plausible size for text.
pt or points - Points are the units most commonly used by typesetters. A 10 point font is a common size for a book, and 12 point fonts are commonly used for reports and on typewriters.
Note that "points" are an absolute unit of measurement. If you move onto a different size screen, or onto paper, your geometry and windows will scale but the text, when set in points, will stay the same.
px or pixels - Many bitmap computer fonts are measured in pixels. If you know exactly the machine you're running on and exactly the font you want, and that font is officially measured in pixels, then px is appropriate to use. Otherwise measuring in pixels might lessen the portability of your program.

The default is "size = 0.03 sru".

[no] extra space [= gap] - The gap between each character is normally zero, but can be customized. The gap is specified in the same way as the font's size. The default is "no extra space".
[no] rotation [= angle] - The argument is either the angle (in degrees) by which the font is rotated clockwise, or "follow path", which orients the text to be perpendicular to the text path. If the display does not support rotation of characters to the desired angle, HOOPS will use the stroked font. The default is "no rotation".
[no] slant [= angle] - The angle by which the text is slanted, from -75 degrees to +75 degrees. The stroked font will be used if the display does not support slanted characters.
[no] transforms [= on | off | character position only] - "Transforms" (or "transforms = on") tells the system to pick a font that can and should be subject to transformations just like regular geometry. In other words, a "transformable" font is subject to scaling, rotations, perspective transformations, etc. Setting "transforms" causes the Text Path to be added onto all of the other transformations.

"No transforms" (or "transforms = off") says that only the starting position of the text (as determined by the Text Alignment) is affected by the camera, the modelling, etc. After that, the text is drawn in the screen coordinate system. Text Path works relative to the screen a (0, 1, 0) path runs straight up the screen.

If the text is drawn in the Camera Target plane (e.g., Z=0), if the Camera Up Vector is (0, 1, 0), if the Camera Field is (2, 2), and if there is no Modelling (this is all the start-up state), then "transforms" and "no transforms" will come out identically placed on the screen. As the camera moves from this position, "transforms" text will change while "no transforms" text will stay the same.

A third choice is available. Since fully-transformable text commonly requires falling back to the stroked font, you can specify "transforms= character position only". In this case all the text transforms involved in positioning the characters will be performed, but the characters themselves will be drawn erect and facing forwards. This allows bitmap characters to still be used.

The default is "no transforms".

Returns

Nothing.

Examples

SclGraphicsOpen mynode
  SclGraphicsSetTextFont "name=roman,size=0.03 sru"
SclGraphicsClose