The Annotated VRML 97 Reference

1 Intro     Concepts     3 Nodes     4 Fields/Events    Conformance
A Grammar     B Java     C JavaScript     D Examples     E Related Info    References
Quick Java         Quick JavaScript         Quick Nodes   

  About the Book
  Copyright © 1997-99
  Purchase the book from

Chapter 3:
Node Reference


+3.47 Text

Text { 
  exposedField  MFString string    []
  exposedField  SFNode   fontStyle NULL
  exposedField  MFFloat  length    []      # [0,INF)
  exposedField  SFFloat  maxExtent 0.0     # [0,INF)

3.47.1 Introduction

The Text node specifies a two-sided, flat text string object positioned in the Z=0 plane of the local coordinate system based on values defined in the fontStyle field (see FontStyle node). Text nodes may contain multiple text strings specified using the UTF-8 encoding as specified by ISO 10646-1:1993 (see [UTF8]). The text strings are stored in the order in which the text mode characters are to be produced as defined by the parameters in the FontStyle node.

The text strings are contained in the string field. The fontStyle field contains one FontStyle node that specifies the font size, font family and style, direction of the text strings, and any specific language rendering techniques that must be used for the text.

The maxExtent field limits and compresses all of the text strings if the length of the maximum string is longer than the maximum extent, as measured in the local coordinate system. If the text string with the maximum length is shorter than the maxExtent, then there is no compressing. The maximum extent is measured horizontally for horizontal text (FontStyle node: horizontal=TRUE) and vertically for vertical text (FontStyle node: horizontal=FALSE). The maxExtent field shall be >= 0.0.

The length field contains an MFFloat value that specifies the length of each text string in the local coordinate system. If the string is too short, it is stretched (either by scaling the text or by adding space between the characters). If the string is too long, it is compressed (either by scaling the text or by subtracting space between the characters). If a length value is missing (for example, if there are four strings but only three length values), the missing values are considered to be 0. The length field shall be >= 0.0.

Specifying a value of 0 for both the maxExtent and length fields indicates that the string may be any length.

Text node: maxExtent and length

Figure 3-56: Text Node maxExtent and length Fields

3.47.2 ISO 10646-1:1993 Character Encodings

Characters in ISO 10646 are encoded in multiple octets. Code space is divided into four units, as follows:

| Group-octet | Plane-octet | Row-octet | Cell-octet |

ISO 10646-1:1993 allows two basic forms for characters:

  1. UCS-2 (Universal Coded Character Set-2). This form is also known as the Basic Multilingual Plane (BMP). Characters are encoded in the lower two octets (row and cell).
  2. UCS-4 (Universal Coded Character Set-4). Characters are encoded in the full four octets.

In addition, three transformation formats (UCS Transformation Format or UTF) are accepted: UTF-7, UTF-8, and UTF-16. Each represents the nature of the transformation: 7-bit, 8-bit, or 16-bit. UTF-7 and UTF-16 are referenced in [UTF8].

UTF-8 maintains transparency for all ASCII code values (0...127). It allows ASCII text (0x0..0x7F) to appear without any changes and encodes all characters from 0x80.. 0x7FFFFFFF into a series of six or fewer bytes.

If the most significant bit of the first character is 0, the remaining seven bits are interpreted as an ASCII character. Otherwise, the number of leading 1 bits indicates the number of bytes following. There is always a zero bit between the count bits and any data.

The first byte is one of the following. The X indicates bits available to encode the character:

 0XXXXXXX only one byte   0..0x7F (ASCII)
 110XXXXX two bytes       Maximum character value is 0x7FF
 1110XXXX three bytes     Maximum character value is 0xFFFF
 11110XXX four bytes      Maximum character value is 0x1FFFFF
 111110XX five bytes      Maximum character value is 0x3FFFFFF
 1111110X six bytes       Maximum character value is 0x7FFFFFFF

All following bytes have the format 10XXXXXX.

As a two byte example, the symbol for a register trade mark is ® or 174 in ISO/Latin-1 (8859/1). It is encoded as 0x00AE in UCS-2 of ISO 10646. In UTF-8, it has the following two byte encoding: 0xC2, 0xAE.

design note

Typically, browsers must consider three parameters when choosing which system font best matches the requested font in the VRML file: the UTF-8 character set contained in Text's string field, and the family and style fields specified in FontStyle. Browsers shall adhere to the following order of priority when choosing the font: character set, then family, then style.

3.47.3 Appearance

Textures are applied to text as follows. The texture origin is at the origin of the first string, as determined by the justification. The texture is scaled equally in both S and T dimensions, with the font height representing 1 unit. S increases to the right, and T increases up.

"2.14 Lighting model" has details on VRML lighting equations and how Appearance, Material and textures interact with lighting.

The Text node does not participate in collision detection.

design note

Significant performance opportunities exist for implementations that avoid generating polygons when rendering the Text node. One approach is to generate two-component (luminance plus alpha with a Material node for color) or four-component (full color plus alpha) texture maps, and apply the generated texture to a rectangle, instead of rendering the explicit polygons at each frame.
A second, potentially complementary, approach is to manage the visible complexity of the text adaptively as a function of distance from the user. A simple method is to generate multiple levels of detail for the text automatically, ranging from high to low resolution plus a very low resolution via "greeking" methods, and lastly to generate an empty level. An even better optimization might combine the texture map generation scheme with the adaptive complexity technique.
And finally, implementations will find it necessary to implement a caching scheme to avoid regenerating the polygons or texture maps at each frame.


The Text node is the most dangerous performance sink in VRML since it is easy to create objects that generate large amounts of polygons. Typically, each character of the Text node generates a set of polygons that can quickly become the limiting factor in your scene's rendering time. Use this node sparingly and limit the strings to short, simple labels.
If you need to present a lot of text to the user, put your VRML world inside a Web page that also contains HTML, or use ImageTexture nodes to display the text. As of this writing (early 1997), The World Wide Web Consortium is in the middle of standardizing the HTML tags used to do this. See their web site for details--; information on HTML can be found at
Even though the VRML standard calls for internationalized text, VRML browsers will probably not be able to display every possible international character due to the lack of complete international fonts.


Use LOD nodes as parents of Text to reduce rendering load when Text is not important.


Use the emissiveColor field of the Material node to set the Text color, and set all other material properties to zero. This produces more readable text (i.e., not subject to lighting effects) and thus significant performance gains in implementations that recognize the hint
     Shape {
       appearance Appearance {
         material Material {     # Hint to browser to ignore lighting
           diffuseColor 0 0 0    # black
           specularColor 0 0 0   # black
           ambientIntensity 0.0  # black
           shininess 0.0         # none
           emissiveColor 1 1 1   # white or whatever
       geometry Text { string "testing" }


Combine a Text node with a screen-aligned Billboard node (i.e., axisOfRotation (0, 0, 0)) to create Text that is readable from any direction. This is especially effective for labels that follow the user's gaze:
     Billboard {
       axisOfRotation 0 0 0
       children Shape {
         geometry Text { string "Smart Label" }


The following example illustrates three typical cases of the Text node (see Figure 3-57). The first Text node shows fully lit 3D text floating over a Box. The text is fixed in space and is readable when the user navigates to face the text. Notice that this text is illuminated by the light source and becomes unreadable when the light shines directly on it (fades into background). The second Text node is combined with a screen-aligned Billboard to face the user at all times. The Material node turns off lighting and results in improved text readability. The third Text node also combines with a Billboard and turns lighting off, but billboards around the Y-axis to face the user:
#VRML V2.0 utf8
Group { children [
  Transform {
    translation -5 0 0
    children [
      Shape {
        geometry Box {}
        appearance DEF A1 Appearance {
          material Material { diffuseColor 1 1 1 }
      Transform {
        translation 0 2.5 0
        children Shape {
          geometry Text {
            string [ "This is a Box.", "Need I say more?" ]
            fontStyle DEF FS FontStyle {
              size 0.5
              family "SERIF"
              style "ITALIC"
              justify "MIDDLE"
          appearance USE A1
  Billboard {
    axisOfRotation 0 0 0    # Screen-aligned
    children [
      Shape { geometry Sphere {} appearance USE A1 }
      Transform {
        translation 0 2.5 0
        children Shape {
          appearance DEF A2 Appearance {
            material Material {     # Hint to render fast
              diffuseColor 0 0 0
              ambientIntensity 0
              emissiveColor 0 0 0
          geometry Text {
            string [ "This is a", "Sphere." ]
            fontStyle USE FS
  Transform {
    translation 5 0 0 
    children Billboard {
      axisOfRotation 0 1 0     # Billboard around Y-axis
      children [
        Shape { geometry Cone {} appearance USE A1 }
        Transform {
          translation 0 2.5 0
            children Shape {
              appearance USE A2
              geometry Text {
                string [ "This is a", "Cone." ]
                fontStyle USE FS
  Background { skyColor 1 1 1 }
  NavigationInfo { type "EXAMINE" }

Text node example

Figure 3-57: Text Node Example