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

#include <Inventor/nodes/SoFont.h>

Inheritance diagram for SoFont:

Public Types
enum	RenderStyle { POLYGON , TEXTURE , TEXTURE_DELAYED , POLYGON_AND_OUTLINE }
	Render style. More...

Public Member Functions
virtual SoType	getTypeId () const
	Returns the type identifier for this specific instance.

	SoFont ()
	Creates a font node with default settings.

virtual void	setOverride (const SbBool state)
	Set the state of the override field.

virtual SbBool	isOverride () const
	Returns the state of the override field.

Public Member Functions inherited from SoNode
virtual SoNode *	copy (SbBool copyConnections=FALSE) const
	Creates and returns an exact copy of the node.

virtual SbBool	affectsState () const
	Returns TRUE if a node has an effect on the state during traversal.

virtual void	touch ()
	Marks an instance as modified, simulating a change to it.

Public Member Functions inherited from SoFieldContainer
void	setToDefaults ()
	Sets all fields in this object to their default values.

SbBool	hasDefaultValues () const
	Returns TRUE if all of the object's fields have their default values.

SbBool	fieldsAreEqual (const SoFieldContainer *fc) const
	Returns TRUE if this object's fields are exactly equal to fc's fields.

void	copyFieldValues (const SoFieldContainer *fc, SbBool copyConnections=FALSE)
	Copies the contents of fc's fields into this object's fields.

SoNONUNICODE SbBool	set (const char *fieldDataString)
	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.

SbBool	set (const SbString &fieldDataString)
	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.

void	get (SbString &fieldDataString)
	Returns the values of the fields of this object in the Open Inventor ASCII file format in the given string.

virtual int	getFields (SoFieldList &list) const
	Appends references to all of this object's fields to resultList, and returns the number of fields appended.

virtual int	getAllFields (SoFieldList &list) const
	Returns a list of fields, including the eventIn's and eventOut's.

virtual SoField *	getField (const SbName &fieldName) const
	Returns a the field of this object whose name is fieldName.

virtual SoField *	getEventIn (const SbName &fieldName) const
	Returns a the eventIn with the given name.

virtual SoField *	getEventOut (const SbName &fieldName) const
	Returns the eventOut with the given name.

SbBool	getFieldName (const SoField *field, SbName &fieldName) const
	Returns the name of the given field in the fieldName argument.

SbBool	enableNotify (SbBool flag)
	Notification at this Field Container is enabled (if flag == TRUE) or disabled (if flag == FALSE).

SbBool	isNotifyEnabled () const
	Notification is the process of telling interested objects that this object has changed.

virtual void	setUserData (void *data)
	Sets application data.

void *	getUserData (void) const
	Gets user application data.

Public Member Functions inherited from SoBase
virtual SbName	getName () const
	Returns the name of an instance.

virtual void	setName (const SbName &name)
	Sets the name of an instance.

void	setSynchronizable (const bool b)
	Sets this to be a ScaleViz synchronizable object.

bool	isSynchronizable () const
	Gets the ScaleViz synchronizable state of this object.

Public Member Functions inherited from SoRefCounter
void	ref () const
	Adds a reference to an instance.

void	unref () const
	Removes a reference from an instance.

void	unrefNoDelete () const
	unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.

int	getRefCount () const
	Returns current reference count.

void	lock () const
	lock this instance.

void	unlock () const
	unlock this instance.

Public Member Functions inherited from SoTypedObject
SbBool	isOfType (const SoType &type) const
	Returns TRUE if this object is of the type specified in type or is derived from that type.

template<typename TypedObjectClass >
SbBool	isOfType () const
	Returns TRUE if this object is of the type of class TypedObjectClass or is derived from that class.

Static Public Member Functions
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

static void	enableJapaneseSF (SbBool flag=TRUE)
	Sets flag to enable strings to be interpreted using the Japanese MBCS encoding.

static SbBool	isJapaneseSFEnabled ()
	Gets flag that indicates whether strings should be interpreted using the MCS Japanese MBCS encoding.

static void	setNumFontCaches (int maxNumCaches)
	Sets the maximum number of caches that can be used for font rendering.

static int	getNumFontCaches ()
	Returns the maximum number of caches that can be used for font rendering.

static int	getCurrNumFontCaches ()
	Returns the current number of caches used for font rendering.

static int	getAvailableFonts (SbString *&strings, SbBool clearDB=FALSE)
	Returns the number of loadable font files and a list of their names.

static SoNONUNICODE void	setFontPaths (char *)
	Specifies paths for searching for font files.

static void	setFontPaths (const SbString &)
	Specifies paths for searching for font files.

static SoNONUNICODE void	addFontPaths (char *)
	Specifies paths for searching for font files.

static void	addFontPaths (const SbString &)
	Specifies paths for searching for font files.

static SbString	getFontPaths ()
	Gets current font path list.

static SoNONUNICODE SbBool	isAvailableFont (char *)
	Returns TRUE if the specified font is available for use by Open Inventor.

static SbBool	isAvailableFont (const SbString &)
	Returns TRUE if the specified font is available for use by Open Inventor.

static void	clearFontNameCache ()
	Clears the Open Inventor internal font name cache, i.e., the list of available fonts.

Static Public Member Functions inherited from SoNode
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

static SoNode *	getByName (const SbName &name)
	A node's name can be set using SoBase::setName().

static int	getByName (const SbName &name, SoNodeList &list)
	A node's name can be set using SoBase::setName().

Static Public Member Functions inherited from SoFieldContainer
static SoType	getClassTypeId ()
	Returns the type of this class.

Static Public Member Functions inherited from SoBase
static SoType	getClassTypeId ()
	Returns type identifier for this class.

Static Public Member Functions inherited from SoTypedObject
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

Public Attributes
SoSFString	name
	This field specifies the font name.

SoSFFloat	size
	This field specifies the font size.

SoSFEnum	renderStyle
	This field specifies the rendering style of the font.

Detailed Description

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

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 and SoAnnoText3, but not with other text nodes, such as 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 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 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 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 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 the 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 SoComplexity::value field) and the current textureQuality (defined by the SoComplexity::textureQuality field) in collaboration with a texture resolution value range defined by the 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 SoGLRenderAction). Or, set the text renderStyle to TEXTURE_DELAYED. This allows delayed rendering of just the text objects. Note that even though setting the 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 SoTextProperty::aliasingFactor.

FILE FORMAT/DEFAULT

name	"defaultFont"
size	10
renderStyle	POLYGON

ACTION BEHAVIOR

SoGLRenderAction

SoCallbackAction

SoGetBoundingBoxAction

SoRayPickAction

SoFontNameElement

SoFontSizeElement

SoFontRenderStyleElement

SoTextOutlineEnabledElement

Member Enumeration Documentation

◆ RenderStyle

enum SoFont::RenderStyle

Render style.

Enumerator
POLYGON	Render font as polygonal objects. (default).
TEXTURE	Render font as texture objects. Warning: Small artifacts may appear around the text because of transparency artifacts. To remove them, please use the TEXTURE_DELAYED value.
TEXTURE_DELAYED	Render font as texture objects, but delay the rendering to prevent transparency artifacts, similar to delaying transparent objects. NOTE: enumeration value available since Open Inventor 6.1
POLYGON_AND_OUTLINE	Render outlining font. Not available for SoText2 text node.

Definition at line 327 of file SoFont.h.

Constructor & Destructor Documentation

◆ SoFont()

SoFont::SoFont ( )

Creates a font node with default settings.

Member Function Documentation

◆ addFontPaths() [1/2]

static SoNONUNICODE void SoFont::addFontPaths ( char * )

static

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 (";")

Non Unicode: This function should not be used in a Unicode application.

◆ addFontPaths() [2/2]

static void SoFont::addFontPaths ( const SbString & )

static

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 (";")

◆ clearFontNameCache()

static void SoFont::clearFontNameCache ( )

static

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

◆ enableJapaneseSF()

static void SoFont::enableJapaneseSF ( SbBool flag = TRUE )

static

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.

◆ getAvailableFonts()

static int SoFont::getAvailableFonts	(	SbString *&	strings,
		SbBool	clearDB = `FALSE`
	)

static

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)". The retrieved string can be passed directly to the SoFont::name field (the "(font file)" substring will be ignored). Internally, this method builds a font name cache. It scans some predefined directories and registers the association "Name : Style" <=> "font file". Passing the clearDB parameter as TRUE empties the font name cache, and then regenerates it.

◆ getClassTypeId()

static SoType SoFont::getClassTypeId ( )

static

Returns the type identifier for this class.

◆ getCurrNumFontCaches()

static int SoFont::getCurrNumFontCaches ( )

static

Returns the current number of caches used for font rendering.

◆ getFontPaths()

static SbString SoFont::getFontPaths ( )

static

Gets current font path list.

◆ getNumFontCaches()

static int SoFont::getNumFontCaches ( )

static

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

◆ getTypeId()

virtual SoType SoFont::getTypeId ( ) const

virtual

Returns the type identifier for this specific instance.

Reimplemented from SoNode.

Reimplemented in SoFontStyle.

◆ isAvailableFont() [1/2]

static SoNONUNICODE SbBool SoFont::isAvailableFont ( char * )

static

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

Non Unicode: This function should not be used in a Unicode application.

◆ isAvailableFont() [2/2]

static SbBool SoFont::isAvailableFont ( const SbString & )

static

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

◆ isJapaneseSFEnabled()

static SbBool SoFont::isJapaneseSFEnabled ( )

static

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.

◆ isOverride()

virtual SbBool SoFont::isOverride ( ) const

inlinevirtual

Returns the state of the override field.

Reimplemented from SoNode.

Definition at line 487 of file SoFont.h.

◆ setFontPaths() [1/2]

static SoNONUNICODE void SoFont::setFontPaths ( char * )

static

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 (";")

Non Unicode: This function should not be used in a Unicode application.

◆ setFontPaths() [2/2]

static void SoFont::setFontPaths ( const SbString & )

static

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 (";")

◆ setNumFontCaches()

static void SoFont::setNumFontCaches ( int maxNumCaches )

static

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 like SoFont::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 orientation
SoText2: font name, size, viewport size, render style, text orientation
SoText3: font name, size, render style, text orientation, profile definition

Note: This list is not exhaustive.

◆ setOverride()

virtual void SoFont::setOverride ( const SbBool state )

inlinevirtual

Set the state of the override field.

see SoNode::setOverride doc.

Reimplemented from SoNode.

Definition at line 481 of file SoFont.h.

Member Data Documentation

◆ name

SoSFString SoFont::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).

Definition at line 317 of file SoFont.h.

◆ renderStyle

SoSFEnum SoFont::renderStyle

This field specifies the rendering style of the font.

Use enum RenderStyle. Default is POLYGON.

NOTE: field available since Open Inventor 5.0

Definition at line 350 of file SoFont.h.

◆ size

SoSFFloat SoFont::size

This field specifies the font size.

The value is in printer's points for 2D text (SoText2) and is in the current (object space) units for 3D text (SoText3). Default is 10.

Definition at line 324 of file SoFont.h.

The documentation for this class was generated from the following file:

Inventor/nodes/SoFont.h

Open Inventor Release 2024.1.3

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

FILE FORMAT/DEFAULT

ACTION BEHAVIOR

SEE ALSO

Member Enumeration Documentation

◆ RenderStyle

Constructor & Destructor Documentation

◆ SoFont()

Member Function Documentation

◆ addFontPaths() [1/2]

◆ addFontPaths() [2/2]

◆ clearFontNameCache()

◆ enableJapaneseSF()

◆ getAvailableFonts()

◆ getClassTypeId()

◆ getCurrNumFontCaches()

◆ getFontPaths()

◆ getNumFontCaches()

◆ getTypeId()

◆ isAvailableFont() [1/2]

◆ isAvailableFont() [2/2]

◆ isJapaneseSFEnabled()

◆ isOverride()

◆ setFontPaths() [1/2]

◆ setFontPaths() [2/2]

◆ setNumFontCaches()

◆ setOverride()

Member Data Documentation

◆ name

◆ renderStyle

◆ size