Class SoFont
- java.lang.Object
-
- com.openinventor.inventor.Inventor
-
- com.openinventor.inventor.misc.SoBase
-
- com.openinventor.inventor.fields.SoFieldContainer
-
- com.openinventor.inventor.nodes.SoNode
-
- com.openinventor.inventor.nodes.SoFont
-
- All Implemented Interfaces:
SafeDisposable
- Direct Known Subclasses:
SoFontStyle
public class SoFont extends SoNode
Node that defines font name, size, and type for text. This node defines the current font type and point size for all subsequent text shapes in the scene graph. Depending on the font and render style selected, text shapes may be generated as polygons, lines, or textures.Starting with Open Inventor 6.0, text computation is done using the FreeType 2 library (www.freetype.org). FreeType is a customizable and portable software font engine which is capable of producing high-quality output. FreeType allows support of more font formats than in previous Open Inventor versions: TrueType, Type 1, CID-keyed Type 1, CFF, SFNT-based bitmap, X11 PCF (including gz compressed fonts), Windows FNT, BDF, PFR, dfont, etc.
Starting with Open Inventor 6.0, Unicode text strings are supported. Please note that many fonts have limited support for Unicode characters, especially the Japanese, Chinese, and Korean glyphs.
Some font representing large extended characters and symbols Unicode set can be found:
- Free Quivira font can be found at
http://www.quivira-font.com - Open Source Code2000 font can be found at
http://www.fontspace.com/james-kass/code2000 - GNU GPL Unifont can be found at
http://www.unifoundry.com/unifont.html
Note:
SoFont
will not issue an error message if the specified font is not found at runtime. It will quietly use the default font (e.g. Times New Roman on Windows) as a fallback. Applications can use the static method isAvailableFont() to check if a specific font is available. Default font can be setup explicitly by enironment variable OIV_FONT_NAME or programmatically see SoFontNameElement.setDefault()SoFontNameElement.getDefault()
.Font name:
- Common Font:
The font name can be set either of two ways:
- specifying directly the font file name (e.g., arial.ttf) with an absolute or relative path, or no path.
- specifying the font family name and font style name with the form "family : style".
Typical family names include:
- Arial
- Courier New
- Times New Roman
Typical style names include:
- Bold
- Italic
- Bold Italic
- Arial
Loadable fonts:
The names of all loadable font files available in your environment (depending on Open Inventor environment variables) can be obtained by calling getAvailableFonts().Font file location:
To find the font file on your system, Open Inventor uses several rules. The following directories are searched (in this order):
- 1 - Current directory
- 2 - $OIV_FONT_PATH
- 3 - System-default font directory
- 4 - $OIVHOME/data/fonts
The system-default font directory depends on the platform:
Windows (Retrieved from the registry. Often c:/Windows/Fonts) Solaris /usr/openwin/lib/X11/fonts/Type1/outline AIX /usr/lib/X11/fonts/Type1/DPS HP-UX /usr/lib/X11/fonts/type1.st/typefaces OSF /usr/lib/X11/fonts/Type1Adobe Linux /usr/share/X11/fonts;/usr/share/fonts;/usr/lib/X11/fonts MacOS /Library/Fonts Other /usr/lib/DPS/outline/base Environment variable OIV_FONT_PATH contains a colon-separated or semicolon-separated list of directories to search for font definition files.
- Stroke Fonts:
Stroke fonts, which are drawn with vectors rather than triangles, can provide higher performance, and also better readability at small sizes. Stroke fonts can be used with
SoText3
andSoAnnoText3
, but not with other text nodes, such asSoAsciiText
. Stroke fonts cannot be extruded. Stroke fonts character code valid values must be in the range [32 .. 127]To use a stroke font, specify one of the following stroke font names:
"OIV_Simplex_TGS"
"OIV_Simplex_Roman"
"OIV_Complex_Roman"
"OIV_Duplex_Roman"
"OIV_Triplex_Roman"
"OIV_Simplex_Script"
"OIV_Complex_Script"
"OIV_Simplex_Greek"
"OIV_Complex_Greek"
"OIV_Gothic_German"
"OIV_Gothic_Italian"
"OIV_Gothic_English"
"OIV_Complex_Cyrillic"
"OIV_Upper_Case_Mathematics"
"OIV_Lower_Case_Mathematics"
"OIV_Music"
"OIV_Meteorology"
"OIV_Symbols"
"OIV_Astrology"
"OIV_Complex_Italic"
"OIV_Triplex_Italic"The following figure shows an assortment of characters from each stroke font.
Stroked fonts are subject to the current line attributes, line width and line pattern, which are specified with
SoDrawStyle
.By default, the stroke font files are found in $OIVHOME/data/fonts. If you move them to a different directory, set the environment variable OIV_STROKE_FONT_PATH to be the path to the new directory.
Open Inventor uses several rules to find the font file on your system. The following directories are searched (in this order): (NB: If one of these directories exists, the rest are ignored)
- 1 - $OIV_STROKE_FONT_PATH
- 2 - $OIVHOME/data/fonts
- 3 - ./fonts/
Stroke fonts - Kanji and Katakana:
Additional stroke font files are available for Kanji and Katakana output. To produce Kanji or Katakana stroke output, set the font to any one of the stroke font names. Then, for the text string, pass the desired multi-byte character string (MBCS) to Open Inventor, using the usual techniques. The font file name is not used except as a flag to indicate that stroke output should be produced.
Making a call to the getAvailableFonts() method causes Open Inventor to build an internal font name cache. This cache allows quick access to a newly requested font name without requiring Open Inventor to parse all found font files on your system. In the general case, when the
name
field changes, Open Inventor searches for the corresponding font file and adds its name to its cache for faster retrieval the next time. For example, a request to "Arial : Regular" font name will be internally associated with the arial.ttf font file. The next time "Arial : Regular" is requested, Open Inventor will use arial.ttf. Specifying a not-previously-accessed string as a font name will cause Open Inventor to parse this new string to find a new association. If no association is found, a default font is used for this association. For instance, "Arial : Regul" doesn't necessarily correspond to the arial.ttf font file. To reset the font name cache, call the getAvailableFonts() method and specify the clearDB parameter as trueFont rendering - caching strategy:
The maximum number of caches used during text rendering is specified by the OIV_MAX_FONT_CACHES environment variable. The default number of caches is 20. A cache corresponds to a set of parameters that are taken into account during the computation of a text string. These parameters can be, depending on the kind of text node you are using, font name, size, complexity, etc. The same cache is used for strings that have exactly the same appearance (but not necessarily the same characters). Note that the cache depends on color only for text bitmap rendering. That is, 2D text with renderStyle POLYGON.
It's important to specify an appropriate value for the maximum number of font caches as application performance can be highly dependent on the font caching. In fact, if not enough caches are available, in some cases, Open Inventor will have to recompute text metrics.
Font render style:
The
renderStyle
field allows you to control the rendering mode for the font. It's possible to render 3D text, e.g.SoText3
, using filled polygons (default), filled and outlined polygons or textured quads. It's possible to render 2D text, e.g.SoText2
, using bitmaps (default) or textured quads.Text rendered in POLYGON renderStyle with high complexity (for nice appearance) may require a large number of polygons and reduce performance. Quality is controlled by the value field of
SoComplexity
.Text rendered in TEXTURE modes uses very few polygons and takes advantage of fast texturing hardware on modern graphics boards. Quality is controlled by the textureQuality field of
SoComplexity
.
NOTE: When using a TEXTURE renderStyle, it is not possible to apply a texture image (e.g.SoTexture2
) to the text geometry and theSoText3
geometry is not extruded even if the parts field is set to ALL.Textured font rendering considerations:
Texture generation quality depends on the current complexity (defined by the
SoComplexity.value
field) and the current textureQuality (defined by theSoComplexity.textureQuality
field) in collaboration with a texture resolution value range defined by theSoTextProperty.textureQualityRange
field. Increasing these values will improve the quality of the output, but at the cost of decreased performance and increased memory consumption.If render style TEXTURE is selected, then a texture image is generated for each character. The image of the character is automatically antialiased, which means that some pixels in the texture image will be transparent or partially transparent. Text rendered in this mode is a "transparent" object like any other transparent geometry, and may be rendered incorrectly depending on the order in which objects are rendered. To avoid this issue, you can set the transparency type for rendering the scene graph to, for example, SORTED_PIXEL (see
SoGLRenderAction
). Or, set the textrenderStyle
to TEXTURE_DELAYED. This allows delayed rendering of just the text objects. Note that even though setting therenderStyle
field to TEXTURE_DELAYED is a very simple solution, it can reduce performance due to less efficient render caching. Another option is to move the text node definition in the scene graph to be after all shapes.For text rendering with small font sizes, the default anti-aliasing can lead to undesirable blurring effects. The anti-aliasing level can be changed through the use of the
SoTextProperty.aliasingFactor
.File format/default:
Font {
name "defaultFont" size 10 renderStyle POLYGON Action behavior:
SoGLRenderAction
,SoCallbackAction
,SoGetBoundingBoxAction
,SoRayPickAction
Sets the font name and size in the current traversal state. Sets:SoFontNameElement
,SoFontSizeElement
,SoFontRenderStyleElement
,SoTextOutlineEnabledElement
- See Also:
SoAnnoText3
,SoAsciiText
,SoText2
,SoText3
,SoTextProperty
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SoFont.RenderStyles
Render style.-
Nested classes/interfaces inherited from class com.openinventor.inventor.nodes.SoNode
SoNode.RenderModes
-
Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor
Inventor.ConstructorCommand
-
-
Field Summary
Fields Modifier and Type Field Description SoSFString
name
This field specifies the font name.SoSFEnum<SoFont.RenderStyles>
renderStyle
This field specifies the rendering style of the font.SoSFFloat
size
This field specifies the font size.-
Fields inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle
-
-
Constructor Summary
Constructors Constructor Description SoFont()
Creates a font node with default settings.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
addFontPaths(java.lang.String name_12198)
Specifies paths for searching for font files.static void
clearFontNameCache()
Clears the Open Inventor internal font name cache, i.e., the list of available fonts.static void
enableJapaneseSF()
Calls enableJapaneseSF(true).static void
enableJapaneseSF(boolean flag)
Sets flag to enable strings to be interpreted using the Japanese MBCS encoding.static int
getCurrNumFontCaches()
Returns the current number of caches used for font rendering.static java.lang.String
getFontPaths()
Gets current font path list.static int
getNumFontCaches()
Returns the maximum number of caches that can be used for font rendering.static boolean
isAvailableFont(java.lang.String name_12200)
Returns true if the specified font is available for use by Open Inventor.static boolean
isJapaneseSFEnabled()
Gets flag that indicates whether strings should be interpreted using the MCS Japanese MBCS encoding.static void
setFontPaths(java.lang.String name_12196)
Specifies paths for searching for font files.static void
setNumFontCaches(int maxNumCaches)
Sets the maximum number of caches that can be used for font rendering.-
Methods inherited from class com.openinventor.inventor.nodes.SoNode
affectsState, callback, copy, copy, distribute, doAction, getAlternateRep, getBoundingBox, getByName, getMatrix, getPrimitiveCount, getRenderEngineMode, getRenderUnitID, GLRender, GLRenderBelowPath, GLRenderInPath, GLRenderOffPath, grabEventsCleanup, grabEventsSetup, handleEvent, isBoundingBoxIgnoring, isOverride, pick, rayPick, search, setOverride, touch, write
-
Methods inherited from class com.openinventor.inventor.fields.SoFieldContainer
copyFieldValues, copyFieldValues, enableNotify, fieldsAreEqual, get, getAllFields, getEventIn, getEventOut, getField, getFieldName, hasDefaultValues, isNotifyEnabled, set, setToDefaults
-
Methods inherited from class com.openinventor.inventor.misc.SoBase
dispose, getName, isDisposable, isSynchronizable, setName, setSynchronizable
-
Methods inherited from class com.openinventor.inventor.Inventor
getNativeResourceHandle
-
-
-
-
Field Detail
-
name
public final SoSFString name
This field specifies the font name. The font name can be set either of two ways:- specifying directly the font file name (e.g., arial.ttf) with an absolute or relative path, or no path.
- specifying the font family name and font style name with the form "family : style". Default is "defaultFont" (system dependent).
-
size
public final SoSFFloat size
-
renderStyle
public final SoSFEnum<SoFont.RenderStyles> renderStyle
This field specifies the rendering style of the font. . Default is POLYGON.- Since:
- Open Inventor 5.0
-
-
Method Detail
-
enableJapaneseSF
public static void enableJapaneseSF()
Calls enableJapaneseSF(true).
-
setNumFontCaches
public static void setNumFontCaches(int maxNumCaches)
Sets the maximum number of caches that can be used for font rendering. Default is 20. This number corresponds to the number of changes that can be applied to a font: for example, to use the "Arial" and the "Times" fonts one after the other, two caches are created. Subsequently changing a rendering property likeSoFont.renderStyle
causes the creation of new caches. Properties that cause a cache to be rebuilt include the following:SoAsciiText
: font name, size, render style, text orientationSoText2
: font name, size, viewport size, render style, text orientationSoText3
: font name, size, render style, text orientation, profile definition
Note: This list is not exhaustive.
-
isJapaneseSFEnabled
public static boolean isJapaneseSFEnabled()
Gets flag that indicates whether strings should be interpreted using the MCS Japanese MBCS encoding. This encoding is only used when a stroke font is specified.
-
isAvailableFont
public static boolean isAvailableFont(java.lang.String name_12200)
Returns true if the specified font is available for use by Open Inventor. Internally, this method builds a font name cache (once only). It scans some predefined directories and registers the association "Name : Style" <=> "font file".
-
enableJapaneseSF
public static void enableJapaneseSF(boolean flag)
Sets flag to enable strings to be interpreted using the Japanese MBCS encoding. This encoding is only used when a stroke font is specified. Default is true.Set this flag to false if you want to use characters in the range 128-255 (ISO Latin-1) with stroke fonts.
NOTE: In this case the TGS Roman Simplex font will be used regardless of the stroke font specified (limitation).[Win32] If the current code page is Japanese, the standard Microsoft MBCS encoding is used independent of this flag.
-
getNumFontCaches
public static int getNumFontCaches()
Returns the maximum number of caches that can be used for font rendering.
-
addFontPaths
public static void addFontPaths(java.lang.String name_12198)
Specifies paths for searching for font files. Use this method to add new font paths to the current list of searched paths. The paths must be separated by a semicolon (";")
-
getFontPaths
public static java.lang.String getFontPaths()
Gets current font path list.
-
clearFontNameCache
public static void clearFontNameCache()
Clears the Open Inventor internal font name cache, i.e., the list of available fonts.
-
getCurrNumFontCaches
public static int getCurrNumFontCaches()
Returns the current number of caches used for font rendering.
-
setFontPaths
public static void setFontPaths(java.lang.String name_12196)
Specifies paths for searching for font files. Using this method overrides all other font path definitions, i.e., Open Inventor environment variables and default system font directories. The paths must be separated by a semicolon (";")
-
-