HC_Set_Text_Font

void HC_Set_Text_Font(char const *list)

Chooses the character style to use for text.

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.

Supported Options:: background, bold, extra space, exterior, greeking limit, greeking mode, italic, layout, line spacing, name, overline, preference, renderer, rotation, size, size tolerance, slant, strikethrough, transforms, underline, width scale
DETAILS

Each individual text font option inherits up and down the segment tree and is Set independently of all the other choices. You might find yourself calling Set_Text_Font() several times in a row, feeding in more choices each time. The new choices are merged in with the old as they arrive. (Note though that UnSet_Text_Font() removes all the information for the attribute for that segment - use UnSet_One_Text_Font() to remove the setting for just one option.)

The following choices are recognized:

[no] background [= option, option…]

Legal values for option include:

margins: 1 to 4 specifiers of extra distances, interpreted by the background shape. Using percentages is perhaps the most intuitive, but margins can be set with other units such as sru’s, oru’s, etc. By default, the first margin is defined as 50% of a normal capital letter. If all four margins aren’t set, the margins will repeat. For example:

margins = 50% will set all four margins to 50%

margins = 50%, 15% will set margins 1 and 3 to 50%, margins 2 and 4 to 15%

margins = 50%, 15%, 10% will set margins 1 and 4 to 50%, margin 2 to 15%, and margin 3 to 10%
shape: Sets the background to a predefined shape (oval, box, rounded box, or ellipse) or a custom shape specified by Define_Shape.

Examples:

Set_Text_Font (“background = shape = oval”);
Set_Text_Font (“background = margins = (50%, 15%)”);

bold = [on | off]

Draws each character in bold form. For certain fonts HOOPS may not be able to generate a bold font, and in this case HOOPS will generate a warning. Default is off.

[no] decoration style [=option] Sets the color, visibility, edge, line patterns, or arrowheads using a predefined style specified by Define_Named_Style .

Example:

Set_Text_Font (“decoration style = my style”);

[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”.

exterior [= on | off]

Draws each character in outline form. Default is off.

[no] greeking limit = fff oru/wru/pts

This option sets the minimum text size for which a rectangular symbol will be substituted. Default is “no greeking limit”, i.e. no text greeking at all.

greeking mode = [none|lines|box]

Controls the type of geometry drawn when the size of the text is less than that specified by the greeking limit. “none” means draw nothing if the text is below the greeking limit. “lines” means draw a simple grid of lines. “box” means draw a filled box, preferably using a halftone stipple. The default setting is “greeking mode = lines”.

italic = [on | off]

Draws each character in italic form. For certain fonts HOOPS may not be able to generate an italic font, and in this case HOOPS will generate a warning. Default is off.

layout = [default | unicode]

Setting the layout to default uses the legacy HOOPS font layout, which outputs all fonts from left to right.

Setting the layout to unicode allows for bi-directional font layout. This is the best option for most circumstances. The limitation of this setting is that adjustments to individual characters (e.g., offsets, rotations) are not possible with unicode layout.

line spacing = fff

This option controls line spacing when carriage returns are used in text strings. The float value is multiplied by the current size of the text font. Default spacing is 1.25 (* current font size).

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 HOOPS -recognized “generic” names, HOOPS will look through the selection of fonts that are available on your display 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. For example, the font used in this sentence.

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 built-in HOOPS 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.

And the “specific” fonts built into HOOPS are:

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.

Kuma A “JIS X0208” (Kanji) simplex monospace stroked font. At present this font only includes level one of X0208 (3, 588 characters).

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 (see your driver installation guide notes), 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.

Value can be a list of font choices, separated by commas and surrounded by parentheses. HOOPS will first try to load the first-named font, and if that fails it will move on to the second, etc. This allows for some portability of font specifications.

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).

If value is not one of the built-in fonts, then the first time the text is displayed, it will trigger a font search, which can be fairly time-consuming if there are many font files in your font directory (or list of directories). See the notes on the “extended font search” system option (Define_System_Options()) for instructions on how to avoid this.

The default for name is “sans serif”.

overline = [on | off]

Draws each character with an overline. Default is off.

preference = (option, option, option…)

Tells HOOPS which version of a text string to use at various font sizes. Using this interface allows the user to switch between driver- and vector-based fonts depending on the screen size of the font. Additionally, you can also specify polyline outlines of the freetype characters as a preference. Legal values for option include:

smaller = [exterior|vector|raster|default]
larger = [exterior|vector|raster|default]

For both smaller and larger, use “vector” for vector based fonts or “raster” for bitmap based fonts or “exterior” to render characters in outline form. “default” instructs HOOPS to choose the default for whichever driver is being used. Typically the default is “raster” for display drivers and “vector” for hardcopy drivers.

cutoff = xxx

This can be any normal text size specification.

exterior|vector|raster|default

Applies one preference to all font sizes.

The default setting is “preference=default”

renderer = [default|driver|truetype|defined]

Allows the user to specify which HOOPS font-handling subsystem should be used to locate the specified font and make it available to HOOPS. If ‘default’ is set then all font-handling subsystems are considered, and the naming convention of fonts remains consistent with previous HOOPS releases. If ‘driver’ is specified, then only driver fonts will be considered. If ‘truetype’ is specified then only fonts accessible by HOOPS Truetype-handling subsystem will be considered. If ‘defined’ is specified, then only fonts created via HC_Define_Font() are considered. When the setting is either ‘driver’ or ‘truetype’ then the name of the font will map over to the standard name of the font on the display system. The default setting is ‘default’.

For example: assume the request font name is ‘arial’. By default HOOPS will look for that font using the current HOOPS driver, and then using its Truetype-handling subsystem. This is a longstanding HOOPS behavior.

If ‘renderer=driver’, HOOPS only checks if the current driver can find and support the font. If its not found, HOOPS will fall back to stroked.

If ‘renderer=truetype’, HOOPS only checks if the Truetype-handling subsystem can find and support that font. If its not found, HOOPS will fall back to stroked.

[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”.

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 menus, for example.

wru “Window relative units”. Similar to sru, but the text is measured relative to the local HOOPS window, rather than the outermost window. This is sometimes useful when the user is rescaling internal HOOPS windows on the fly.

wsu “World space units”. This number indicates the text size in world space. This is very similar to “oru” except that it includes any scales from any modelling matrices applying to the containing segment.

pt or points Points are the units most commonly used by typesetters. In HOOPS, a point is equal to 1/72 inch. 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] size tolerance [= tolerance-spec]

Most system fonts are bitmap fonts and only come in a fixed selection of sizes (see Show_Font_Info() .) If the exact size you requested is not available, HOOPS has to decide what to do. If “no size tolerance” is specified, the nearest bitmap font (usually the next smaller) is scaled up to the size - if your display system knows how to scale bitmaps. If “no size tolerance” is specified, the size you wanted isn’t there, and your system doesn’t scale bitmaps, HOOPS gives up and uses stroked font.

On the other hand, if it’s all right to use a font a little smaller than requested you can say how much smaller is okay by specifying size tolerance with a value. Tolerance-spec is coded in the style of size-spec above. Besides sru, wru, etc., a “%” can be used, which makes the size tolerance a relative percentage of the current requested text size.

The default is “size tolerance = 50%”.

[no] slant [= angle]

The angle by which the text is slanted, from -75 degrees to +75 degrees. HOOPS will use the stroked font if the display does not support slanted characters.

strikethrough = [on | off]

Draws each character with a strikethrough. Default is off.

[no] transforms [= on | off | character position only|character position adjusted]

“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 HOOPS 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.

Two other choices remain. Since fully-transformable text commonly requires falling back to the stroked font, you can specify “transforms= character position only” or “transforms= character position adjusted”. In both cases, 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 difference between the “aligned” case and the “only” case is as follows. Note that you must use “.” Text_Alignment or one of its variants as well as the “rotation=follow path” Text_Font options. In this case if the transform is set to “character position adjusted” when changing the camera in such a way that the text would become upside down, the text up-direction will be automatically flipped. The “only” case will not perform this auto-flipping. It is otherwise identical to “adjusted”.

The default is “no transforms”.

underline = [on | off]

Draws each character with an underline. Default is off.

width scale = [ddd]

A floating point number that adjusts a character width.

If a character is not available in the given font, HOOPS may try to fill in by overstriking other characters. If this is not possible, the system will fill in with a character from the stroked font.

NOTES

The default setting of the Text Font attribute - the setting on the root (“/”) segment - may be given a new initial value on most systems by means of the environment variable “HOOPS_TEXT_FONT”.