com.openinventor.inventor.nodes

Class SoText2

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

com.openinventor.inventor.nodes.SoText2

All Implemented Interfaces:

SafeDisposable

public class SoText2
extends SoShape

Screen-aligned 2D text shape node. This node defines one or more strings of 2D text. The text is always horizontal, aligned with the screen and does not change size with distance from the camera. However the position of the text is specified in 3D units and is affected by viewing and modeling transformations. 2D text cannot be rotated, but because it always faces the user, it is often used for annotation, for example labels on axes.

The text position is always at the local origin (0,0,0). Rotations and scales have no effect on the orientation or size of 2D text, just the location.

Note: A transform node, e.g. SoTranslation, must be used to position the text in 3D space.

Text supports both single byte Latin1 (ISO8859-1) characters and multi-byte UNICODE characters. ISO8859-1 is an 8-bit character set which is a superset of the older 7-bit ASCII character set. See the String class for more information.

Rendering:

The typeface and size (default = 10) are specified using an SoFont node. Note that for SoText2 the size is interpreted as a value in pixels, not 3D units.

Setting the SoFont renderStyle field to TEXTURE is recommended for best appearance and performance. (antialiasing is applied).

Additional rendering styles can be applied using an SoTextProperty node, including underline, overline, strikethrough, background and background outline.

SoText2 is drawn using the diffuse color of the current material (SoMaterial). Lighting is not applied, regardless of the lighting model. Textures do not affect SoText2 (note this is independent of the fact that textures are used internally to render SoText2). Complexity (SoComplexity) does not affect SoText2. Drawing styles (SoDrawStyle) other than INVISIBLE do not affect SoText2.

Justification:

Horizontal alignment of the text can be specified using the justification field. Both horizontal and vertical alignment can be controlled using an SoTextProperty node, however the justification setting in the SoText2 node overrides the horizontal setting unless it is explicitly set to INHERITED.

Clipping:

If the transformed position (origin point) of the SoText2 is clipped, then the entire string is clipped, even if some part of the string should conceptually be visible. If the origin point is inside the view volume then the string is clipped similar to other geometry.

Bounding box:

Because 2D text is screen-aligned, it has some unusual characteristics. For example, the 3D bounding box surrounding a 2D text string depends on the current camera and the current viewport size, since changing the field of view or the mapping onto the window changes the relative size of the text with respect to the rest of the scene.

When computing the bounding box of a 2D text node (see SoGetBoundingBoxAction), be careful to:

• Initialize the bounding box action with the correct viewport region.
  Typically this information is queried from the viewer.
• Make sure the action will traverse the camera node.
  Apply the action to a node above the camera or create a path to the 2D text node from the root of the scene graph (e.g. using SoSearchAction).

Picking:

Text can be picked (SoRayPickAction) like any other geometry. If a text node has been picked then SoPickedPoint can return an SoTextDetail object. This object contains information about which string (in a multi-string text node) was picked and which character within the string was picked.

Render caching:

If your Open Inventor version is older than 9.2, then SoText2 nodes using CENTER or RIGHT justification cannot be render cached because the bounding box and justification offset depend on the camera. As a result, no SoSeparator above the SoText2 will be able to build a render cache or a bounding box cache and this can reduce performance. If possible put other geometry, that can be cached, under its own SoSeparator. SoText2 nodes using LEFT justification (the default) can be cached. Since Open Inventor 9.2, SoText2 nodes can be render cached in all cases.

Antialiasing:
Shape Antialiasing type is SoShape.TEXT.

Export limitations:

• SoText2 can be exported to VRML/X3D (SoToVRML2Action), but...
  due to limitations of that file format, the text will not be "screen locked".
• SoText2 can be exported to PDF3D/U3D (SoToPDFAction), but...
  due to limitations of that file format, the text will not be "screen locked".
• SoText2 can be exported to various Hardcopy formats (SoVectorizeAction), but...
  native fonts are used, so the requested font name must be available on the rendering device.

File format/default:

Text2 {

string	""
spacing	1
justification	LEFT

}

Action behavior:

SoGLRenderAction
Draws text based on the current font, at a location based on the current transformation.

SoRayPickAction
Performs a pick on the text. Text will be picked if the picking ray intersects the bounding box of the strings. The string index and character position are available from the SoTextDetail.

SoGetBoundingBoxAction
Computes the bounding box that encloses the text.

See also:

SoFont, SoFullSceneAntialiasing, SoText3, SoTextDetail, SoTextProperty

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoText2.Justifications Justification types.

Nested classes/interfaces inherited from class com.openinventor.inventor.nodes.SoShape

SoShape.ShapeTypes

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
static int	CENTER Deprecated. Use SoText2.Justifications.CENTER instead.
static int	INHERITED Deprecated. Use SoText2.Justifications.INHERITED instead.
SoSFEnum<SoText2.Justifications>	justification Specifies horizontal alignment of strings.
static int	LEFT Deprecated. Use SoText2.Justifications.LEFT instead.
static int	RIGHT Deprecated. Use SoText2.Justifications.RIGHT instead.
SoSFFloat	spacing Defines the distance (in the negative y direction) between the base points of successive strings, measured with respect to the current font height.
SoMFString	string The text string(s) to display.

Fields inherited from class com.openinventor.inventor.nodes.SoShape

boundingBoxIgnoring, LINES, POINTS, POLYGONS, TEXT

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoText2() Creates a 2D text node with default settings.

Method Summary

Methods inherited from class com.openinventor.inventor.nodes.SoShape

getShapeType, isPrimitiveRestartAvailable, isPrimitiveRestartAvailable

Methods inherited from class com.openinventor.inventor.nodes.SoNode

affectsState, callback, copy, copy, distribute, doAction, getAlternateRep, getBoundingBox, getByName, getMatrix, getPrimitiveCount, 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, getEXTERNPROTO, getName, getPROTO, isDisposable, isSynchronizable, setName, setSynchronizable

Methods inherited from class com.openinventor.inventor.Inventor

getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LEFT

@Deprecated
public static final int LEFT

Deprecated. Use SoText2.Justifications.LEFT instead.

CENTER

@Deprecated
public static final int CENTER

Deprecated. Use SoText2.Justifications.CENTER instead.

RIGHT

@Deprecated
public static final int RIGHT

Deprecated. Use SoText2.Justifications.RIGHT instead.

INHERITED

@Deprecated
public static final int INHERITED

Deprecated. Use SoText2.Justifications.INHERITED instead.

string

public final SoMFString string

The text string(s) to display. Each string will appear on its own line.

spacing

public final SoSFFloat spacing

Defines the distance (in the negative y direction) between the base points of successive strings, measured with respect to the current font height. A value of 1 indicates single spacing, a value of 2 indicates double spacing, and so on.

justification

public final SoSFEnum<SoText2.Justifications> justification

Specifies horizontal alignment of strings. With LEFT justification, the left edge of the first line is at the (transformed) origin, and all left edges are aligned. RIGHT justification is similar. CENTER justification places the center of the first string at the (transformed) origin, with the centers of all remaining strings aligned under it. Use enum Justification. Default is LEFT.

Both horizontal and vertical alignment can be specified using an SoTextProperty node. However the justification setting in this node overrides the horizontal setting in SoTextProperty unless this field is set to INHERITED.

Constructor Detail

SoText2

public SoText2()

Creates a 2D text node with default settings.