Click or drag to resize
SoFont Class

Node that defines font name, size, and type for text.

Inheritance Hierarchy

Namespace: OIV.Inventor.Nodes
Assembly: OIV.Inventor (in OIV.Inventor.dll) Version: 2023.1.3.0 (2023.1.3)
Syntax
public class SoFont : SoNode

The SoFont type exposes the following members.

Constructors
  NameDescription
Public methodSoFont

Creates a font node with default settings.

Top
Methods
  NameDescription
Public methodStatic memberAddFontPaths

Specifies paths for searching for font files.

Public methodAffectsState

Returns true if a node has an effect on the state during traversal.

(Inherited from SoNode.)
Public methodCallback
Public methodStatic memberClearFontNameCache

Clears the Open Inventor internal font name cache, i.e., the list of available fonts.

Public methodCopy
Calls Copy(false).
(Inherited from SoNode.)
Public methodCopy(Boolean)

Creates and returns an exact copy of the node.

(Inherited from SoNode.)
Public methodCopyFieldValues(SoFieldContainer)
Calls CopyFieldValues(fc, false).
(Inherited from SoFieldContainer.)
Public methodCopyFieldValues(SoFieldContainer, Boolean)

Copies the contents of fc's fields into this object's fields.

(Inherited from SoFieldContainer.)
Public methodDispose
Releases all resources used by SoDisposable.
(Inherited from SoDisposable.)
Public methodDistribute
(Inherited from SoNode.)
Public methodDoAction
Public methodStatic memberEnableJapaneseSF
Calls EnableJapaneseSF(true).
Public methodStatic memberEnableJapaneseSF(Boolean)

Sets flag to enable strings to be interpreted using the Japanese MBCS encoding.

Public methodEnableNotify

Notification at this Field Container is enabled (if flag == true) or disabled (if flag == false).

(Inherited from SoFieldContainer.)
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Public methodFieldsAreEqual

Returns true if this object's fields are exactly equal to fc's fields.

(Inherited from SoFieldContainer.)
Public methodGet

Returns the values of the fields of this object in the Open Inventor ASCII file format in the given string.

(Inherited from SoFieldContainer.)
Public methodGetAllFields

Returns a list of fields, including the eventIn's and eventOut's.

(Inherited from SoFieldContainer.)
Public methodGetAlternateRep

This method is called by actions to allow the node to provide an "alternate representation" when appropriate (typically depending on the action type).

(Inherited from SoNode.)
Public methodStatic memberGetAvailableFonts(String)
Calls #GetAvailableFonts with clearDB argument to false.
Public methodStatic memberGetAvailableFonts(String, Boolean)
Returns the number of loadable font files and a list of their names. Each name in the list is formatted as follows: "Name : Style : (font file)".
Public methodGetBoundingBox
Public methodStatic memberGetCurrNumFontCaches

Returns the current number of caches used for font rendering.

Public methodGetEventIn

Returns a the eventIn with the given name.

(Inherited from SoFieldContainer.)
Public methodGetEventOut

Returns the eventOut with the given name.

(Inherited from SoFieldContainer.)
Public methodGetField

Returns a the field of this object whose name is fieldName.

(Inherited from SoFieldContainer.)
Public methodGetFieldName

Returns the name of the given field in the fieldName argument.

(Inherited from SoFieldContainer.)
Public methodGetFields

Appends references to all of this object's fields to resultList, and returns the number of fields appended.

(Inherited from SoFieldContainer.)
Public methodStatic memberGetFontPaths

Gets current font path list.

Public methodGetHashCode
Overrides GetHashCode().
(Inherited from SoNetBase.)
Public methodGetMatrix
(Inherited from SoNode.)
Public methodGetName

Returns the name of an instance.

(Inherited from SoBase.)
Public methodStatic memberGetNumFontCaches

Returns the maximum number of caches that can be used for font rendering.

Public methodGetPrimitiveCount
Public methodGetRenderEngineMode

Returns the supported Render engine mode.

(Inherited from SoNode.)
Public methodGetRenderUnitID
(Inherited from SoNode.)
Public methodGetStringName (Inherited from SoBase.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodGLRender
Public methodGLRenderBelowPath
(Inherited from SoNode.)
Public methodGLRenderInPath
(Inherited from SoNode.)
Public methodGLRenderOffPath
(Inherited from SoNode.)
Public methodGrabEventsCleanup
(Inherited from SoNode.)
Public methodGrabEventsSetup
(Inherited from SoNode.)
Public methodHandleEvent
(Inherited from SoNode.)
Public methodHasDefaultValues

Returns true if all of the object's fields have their default values.

(Inherited from SoFieldContainer.)
Public methodStatic memberIsAvailableFont

Returns true if the specified font is available for use by Open Inventor.

Public methodIsBoundingBoxIgnoring

This method is used by getBoundingBox action traversal to know if the current node must be traversed or not, ie the bounding should be ignored.

(Inherited from SoNode.)
Public methodStatic memberIsJapaneseSFEnabled

Gets flag that indicates whether strings should be interpreted using the MCS Japanese MBCS encoding.

Public methodIsNotifyEnabled

Notification is the process of telling interested objects that this object has changed.

(Inherited from SoFieldContainer.)
Public methodIsOverride

Returns the state of the override field.

(Overrides SoNodeIsOverride.)
Public methodIsSynchronizable

Gets the ScaleViz synchronizable state of this object.

(Inherited from SoBase.)
Public methodPick
Public methodRayPick
(Inherited from SoNode.)
Public methodSearch
(Inherited from SoNode.)
Public methodSet

Sets one or more fields in this object to the values specified in the given string, which should be a string in the Open Inventor file format.

(Inherited from SoFieldContainer.)
Public methodStatic memberSetFontPaths

Specifies paths for searching for font files.

Public methodSetName (Inherited from SoBase.)
Public methodStatic memberSetNumFontCaches

Sets the maximum number of caches that can be used for font rendering.

Public methodSetOverride

Set the state of the override field.

(Overrides SoNodeSetOverride(Boolean).)
Public methodSetSynchronizable

Sets this to be a ScaleViz synchronizable object.

(Inherited from SoBase.)
Public methodSetToDefaults

Sets all fields in this object to their default values.

(Inherited from SoFieldContainer.)
Public methodToString
Converts this SoBase structure to a human readable string.
(Inherited from SoBase.)
Public methodTouch

Marks an instance as modified, simulating a change to it.

(Inherited from SoNode.)
Public methodWrite
(Inherited from SoNode.)
Top
Properties
  NameDescription
Public propertyIsDisposable
ISafeDisposable interface implementation.
(Inherited from SoDisposable.)
Public propertyname

This field specifies the font name.

Public propertyrenderStyle

This field specifies the rendering style of the font.

Public propertysize

This field specifies the font size.

Public propertyUserData
Gets or sets the user data to be contained by the field container.
(Inherited from SoFieldContainer.)
Top
Remarks

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: OIV.Inventor.Nodes.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 OIV.Inventor.Nodes.SoFont.IsAvailableFont(System.String) 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() OIV.Inventor.Elements.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

Loadable fonts: The names of all loadable font files available in your environment (depending on Open Inventor environment variables) can be obtained by calling ().

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 OIV.Inventor.Nodes.SoText3 and OIV.Inventor.Nodes.SoAnnoText3, but not with other text nodes, such as OIV.Inventor.Nodes.SoAsciiText. 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 OIV.Inventor.Nodes.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.

Font name cache:

Making a call to the () 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 OIV.Inventor.Nodes.SoFont.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 () method and specify the clearDB parameter as true

Font 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 OIV.Inventor.Nodes.SoFont.renderStyle field allows you to control the rendering mode for the font. It's possible to render 3D text, e.g. OIV.Inventor.Nodes.SoText3, using filled polygons (default), filled and outlined polygons or textured quads. It's possible to render 2D text, e.g. OIV.Inventor.Nodes.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 OIV.Inventor.Nodes.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 OIV.Inventor.Nodes.SoComplexity. NOTE: When using a TEXTURE renderStyle, it is not possible to apply a texture image (e.g. OIV.Inventor.Nodes.SoTexture2) to the text geometry and the OIV.Inventor.Nodes.SoText3 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 OIV.Inventor.Nodes.SoComplexity.value field) and the current textureQuality (defined by the OIV.Inventor.Nodes.SoComplexity.textureQuality field) in collaboration with a texture resolution value range defined by the OIV.Inventor.Nodes.SoTextProperty.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 OIV.Inventor.Actions.SoGLRenderAction). Or, set the text OIV.Inventor.Nodes.SoFont.renderStyle to TEXTURE_DELAYED. This allows delayed rendering of just the text objects. Note that even though setting the OIV.Inventor.Nodes.SoFont.renderStyle 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 OIV.Inventor.Nodes.SoTextProperty.aliasingFactor.

FILE FORMAT/DEFAULT

Font {
name "defaultFont"
size 10
renderStyle POLYGON
}

ACTION BEHAVIOR

OIV.Inventor.Actions.SoGLRenderAction, OIV.Inventor.Actions.SoCallbackAction, OIV.Inventor.Actions.SoGetBoundingBoxAction, OIV.Inventor.Actions.SoRayPickAction Sets the font name and size in the current traversal state. Sets: OIV.Inventor.Elements.SoFontNameElement, OIV.Inventor.Elements.SoFontSizeElement, OIV.Inventor.Elements.SoFontRenderStyleElement, OIV.Inventor.Elements.SoTextOutlineEnabledElement

See Also