Functions | |
void | Set_Text_Font (const char *list) |
Chooses the character style to use for text. More... | |
void | UnSet_One_Text_Font (const char *which) |
Removes a given setting established by a previous call to Set_Text_Font(), rather than all settings. More... | |
void | UnSet_Text_Font (void) |
Removes all settings established by a previous call to Set_Text_Font(). More... | |
void Set_Text_Font | ( | const char * | list | ) |
Chooses the character style to use for text.
list | - A quoted string or a string variable containing a list of the desired settings (see below). |
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 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:
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.
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".
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".
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.
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).
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:
And the "specific" fonts built into HOOPS are:
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".
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:
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.
This can be any normal text size specification.
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.
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".
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:
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%".
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.
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".
Draws each character with an underline. Default is off.
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.
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".
void UnSet_One_Text_Font | ( | const char * | which | ) |
Removes a given setting established by a previous call to Set_Text_Font(), rather than all settings.
which | - An individual text font option whose value is to be dis carded. |
No additional details. See Set_Text_Font()
void UnSet_Text_Font | ( | void | ) |
Removes all settings established by a previous call to Set_Text_Font().
No additional details. See Set_Text_Font()