Copyright © 1997 by Rikk Carey and Gavin Bell
This chapter describes the syntax and general semantics of fields and events--the elemental data types used by VRML nodes to define objects (see Chapter 3, Node Reference). Nodes are composed of fields and events (see Chapter 4, Field and Event Reference). The types defined in this chapter are used by both fields and events.
4.1 Introduction
4.1 Introduction
4.1.1 Table of
contents
4.1.2 Description
4.2 SFBool
4.3 SFColor and MFColor
4.4 SFFloat and MFFloat
4.5 SFImage
4.6 SFInt32 and MFInt32
4.7 SFNode and MFNode
4.8 SFRotation and MFRotation
4.9 SFString and MFString
4.10 SFTime
4.11 SFVec2f and MFVec2f
4.12 SFVec3f and MFVec3f
This chapter describes the syntax and general semantics of fields and events, the elemental data types used by VRML nodes to define objects (see Chapter 3, "Node Reference"). Nodes are composed of fields and events (see Chapter 2, "Key Concepts"). The types defined in this chapter are used by both fields and events.
There are two general classes of fields and events: fields/events that contain a single value (where a value may be a single number, a vector, or even an image), and fields/events that contain an ordered list of multiple values. Single-valued fields/events have names that begin with SF. Multiple-valued fields/events have names that begin with MF.
Multiple-valued fields/events are written as an ordered list of values enclosed in square brackets and separated by whitespace (e.g., by commas). If the field or event has zero values, only the square brackets ("[ ]") are written. The last value may optionally be followed by whitespace (e.g., commas or spaces). If the field has exactly one value, the brackets may be omitted. For example, all of the following are valid for a multiple-valued MFInt32 field named foo containing the single integer value 1:
foo 1
foo [1,]
foo [ 1 ]
There are some "missing" MF field types. For example, there is an SFBool field type but no MFBool type. Only the field types used by the 54 nodes in the specification are defined. The practical, immediate benefits of making implementations a little bit smaller were judged to be more important than the intangible benefits of having a more symmetric design or the possible future benefits to language extensions defined using EXTERNPROTO.
The design of the field types is not as conceptually "clean" as it could be. The problem is that some of the field types define only the syntax or structure of the values they contain, while others define both the syntax and the semantics of the values they contain. For example, an SFVec3f field can contain any triple of floating point numbers, regardless of how they are used. An SFColor field is syntactically identical to an SFVec3f field, but it implies something about the semantics of the numbers in the field—they must be between 0.0 and 1.0, and they represent RGB intensities. The field types would be more consistent if either there was no SFColor field type or if the SFVec3f field type was replaced with field types with specific uses--perhaps SFPosition (for a point in space) and SFUnitVector (for a unit vector such as a polygon normal).
It isn't clear which design would be better--one with fewer field types that define only the structure of the fields or one with more field types that define the semantics of the fields. The mix of both found in the current specification works pretty well in practice.
4.2
SFBoolSFBool is a field or event containing a single boolean value. SFBools are written as TRUE or FALSE. For example,
fooBool FALSE
is an SFBool field, fooBool, defining a FALSE value.
The initial value of an SFBool eventOut is FALSE.
It is annoying, but VRML uses "TRUE" and "FALSE" for Boolean values, while Java and JavaScript use "true" and "false." Just remember to use TRUE/FALSE when you are writing the VRML file format, but always use true/false when you are writing Java or JavaScript code.
4.3 SFColor and MFColorSFColor specifies one RGB (red-green-blue) colour triple. MFColor specifies zero or more RGB triples. Each colour is written to the VRML file as an RGB triple of floating point numbers in ISO C floating point format (see [ISOC]) in the range 0.0 to 1.0. For example:
fooColor [ 1.0 0. 0.0, 0 1 0, 0 0 1 ]
is an MFColor field, fooColor, containing the three primary colours red, green, and blue.
The initial value of an SFColor eventOut is (0 0 0). The initial value of an MFColor eventOut is [ ].
Each component (R, G, B) of a color is expressed in VRML as a floating point number (0.0 to 1.0), but most VRML implementations will convert them internally into, at most, 256 discrete levels. So writing out colors with more than three significant digits of precision just makes your VRML files unnecessarily large. Users will not be able to distinguish between color (.005199, .12345, 0) and color (.005, .123, 0).
4.4 SFFloat
and MFFloatSFFloat specifies one single-precision floating point number. MFFloat specifies zero or more single-precision floating point numbers. SFFloats and MFFloats are written to the VRML file in ISO C floating point format (see [ISOC]). For example:
fooFloat [ 3.1415926, 12.5e-3, .0001 ]
is an MFFloat field, fooFloat, containing three floating point values.
The initial value of an SFFloat eventOut is 0.0. The initial value of an MFFloat eventOut is [ ].
Legal values for single-precision floating point values range from 1.0e38 to -1.0e38, with more than seven significant decimal digits of accuracy. Seven digits of accuracy means you can model something 10 km big with about plus or minus 1-mm accuracy. Usually you won't need such high accuracy and you can make your VRML files much smaller by writing out floating point values with less precision.
4.5 SFImageThe SFImage field or event defines a single uncompressed 2-dimensional pixel image. SFImage fields and events are written to the VRML file as three integers representing the width, height and number of components in the image, followed by width*height hexadecimal or integer values representing the pixels in the image, separated by whitespace:
fooImage <width> <height> <num components> <pixels values>
Pixel values are limited to 256 levels of intensity (i.e., 0-255 decimal or 0x00-0xFF hexadecimal). A one-component image specifies one-byte hexadecimal or integer values representing the intensity of the image. For example, 0xFF is full intensity in hexadecimal (255 in decimal), 0x00 is no intensity (0 in decimal). A two-component image specifies the intensity in the first (high) byte and the alpha opacity in the second (low) byte. Pixels in a three-component image specify the red component in the first (high) byte, followed by the green and blue components (e.g., 0xFF0000 is red, 0x00FF00 is green, 0x0000FF is blue). Four-component images specify the alpha opacity byte after red/green/blue (e.g., 0x0000FF80 is semi-transparent blue). A value of 0x00 is completely transparent, 0xFF is completely opaque. Note that alpha equals (1.0 - transparency), if alpha and transparency range from 0.0 to 1.0.
Each pixel is read as a single unsigned number. For example, a 3-component pixel with value 0x0000FF may also be written as 0xFF (hexadecimal) or 255 (decimal). Pixels are specified from left to right, bottom to top. The first hexadecimal value is the lower left pixel and the last value is the upper right pixel.
For example,
fooImage 1 2 1 0xFF 0x00
is a 1 pixel wide by 2 pixel high one-component (i.e., greyscale) image, with the bottom pixel white and the top pixel black. As another example,
fooImage 2 4 3 0xFF0000 0xFF00 0 0 0 0 0xFFFFFF 0xFFFF00
# red green black.. white yellow
is a 2 pixel wide by 4 pixel high RGB image, with the bottom left pixel red, the bottom right pixel green, the two middle rows of pixels black, the top left pixel white, and the top right pixel yellow.
The initial value of an SFImage eventOut is (0 0 0).
The SFImage field is used only by the PixelTexture node and is meant to be used only for small images or images that are algorithmically generated by a Script node. For larger images it is generally much better to use ImageTexture nodes and store the images in PNG, JPEG, or GIF files, since those file formats can compress the images, making them much faster to transmit across the network.
4.6 SFInt32
and MFInt32The SFInt32 field and event specifies one 32-bit integer. The MFInt32 field and event specifies zero or more 32-bit integers. SFInt32 and MFInt32 fields and events are written to the VRML file as an integer in decimal or hexadecimal (beginning with '0x') format. For example:
fooInt32 [ 17, -0xE20, -518820 ]
is an MFInt32 field containing three values.
The initial value of an SFInt32 eventOut is 0. The initial value of an MFInt32 eventOut is [ ].
A 32-bit integer can hold a value that ranges from about negative two billion to positive two billion.
4.7 SFNode
and MFNodeThe SFNode field and event specifies a VRML node. The MFNode field and event specifies zero or more nodes. The following example illustrates valid syntax for an MFNode field, fooNode, defining four nodes:
fooNode [ Transform { translation 1 0 0 }
DEF CUBE Box { }
USE CUBE
USE SOME_OTHER_NODE ]
The SFNode and MFNode fields and events may contain the keyword NULL to indicate that it is empty.
The initial value of an SFNode eventOut is NULL. The initial value of an MFNode eventOut is [ ].
SFNode and MFNode are used whenever a node needs to include the definition of another node in order to define itself. The syntax of SFNode and MFNode is identical to standard VRML file syntax—you simply specify the node definition as the field value. The most common use of SFNode/MFNode is in grouping nodes that contain children nodes. For example, the Group node has an exposed MFNode field named children. This field contains a list of node definitions that represent the child nodes that the Group encapsulates. Remember that node definitions may contain DEF names or USE instantiations. In the following file excerpt, the Group node specifies five children nodes in the children field. Note that the last two children are specified through the USE syntax:
...
DEF S1 Shape { geometry Sphere {} }
Group {
children [ # an MFNode exposedField
Shape { geometry Cone {} } # first child
Shape { geometry Box {} } # second child
DEF T1 Transform { ... } # third child (named)
USE S1 # fourth child (instance of S1)
USE T1 # fifth child (instance of T1)
]
}
4.8 SFRotation and MFRotationThe SFRotation field and event specifies one arbitrary rotation. The MFRotation field and event specifies zero or more arbitrary rotations. An SFRotation is written to the VRML file as four ISO C floating point values (see [ISOC])separated by whitespace. The first three values specify a normalized rotation axis vector about which the rotation takes place. The fourth value specifies the amount of right-handed rotation about that axis in radians. An MFRotation specifies 0 or more rotations. For example, an SFRotation containing a PI radians rotation about the Y axis is:
fooRot 0.0 1.0 0.0 3.14159265
The 3x3 matrix represention of a rotation (x y z a) is
[ tx2+c txy+sz txz-sy
txy-sz ty2+c tyz+sx
txz+sy tyz-sx tz2+c ]
where c = cos(a), s = sin(a), and t = 1-c
The initial value of an SFRotation eventOut is (0 0 1 0). The initial value of an MFRotation eventOut is [ ].
It might have been better to name these fields SF/MFOrientation, because they really represent a "final" orientation of something and do not imply anything about how it might have been rotated to get to that orientation. A common VRML 1.0 extension was a Rotor node that used an SFRotation field to define how the object should rotate. A very common error was to use a zero rotation angle about a desired rotation axis to define the rotation. Browsers that stored rotations internally as quaternions or matrices would immediately convert the SFRotation into their internal representation and lose the desired rotation axis. The end result was a rotation about (usually) the z-axis and a very frustrated user.
If you are writing extension nodes or Scripts that truly require a rotation axis and a rotation angle, do not use an SFRotation field. Instead, store the axis in an SFVec3f field and store the angle in an SFFloat field. The Rotor node would have worked perfectly if the desired rotation axis was specified as an SFVec3f field.
Be careful. One rotation has multiple equivalent representations in the axis-plus-angle form chosen by VRML to represent rotations. Zero rotations can be especially troublesome; (1, 0, 0, 0) and (0, 1, 0, 0) are equivalent (and are equivalent to any rotation of the form (x, y, z, 0)). Similarly, a rotation (x, y, z, angle) is equivalent to the rotation (-x, -y, -z, -angle).
This means that you must not assume that the particular values you choose for the axis and angle to represent a rotation will be preserved by a browser. For example, a browser may read in an SFRotation value of (1, 0, 0, 0), but may write the value back out (or return it to a Script node) as (0, 0, 1, 0). They are equivalent rotations, but if you were expecting to get exactly the same axis and angle, you will be surprised.
Also note that these fields cannot store multiple rotations about an axis, for exactly the same reason: A rotation (x, y, z, angle) is the same as (x, y, z, i×2×angle), for any positive or negative integer i.
4.9 SFString
and MFStringThe SFString and MFString fields and events contain strings formatted with the UTF-8 universal character set (see [UTF8]). SFString specifies a single string. The MFString specifies zero or more strings. Strings are written to the VRML file as a sequence of UTF-8 octets enclosed in double quotes (e.g., "string").
Any characters (including LineFeeds and '#') may appear within the quotes. A double quote character within the string is preceded with a backslash. A backslash character within the string is also preceded with a backslash forming two backslashes. For example:
fooString [ "One, Two, Three", "He said, \"Immel did it!\"" ]
is an MFString field, fooString, with two valid strings.
The initial value of an SFString eventOut is "" (the empty string). The initial value of an MFString eventOut is [ ].
4.10 SFTimeThe SFTIme field and event specifies a single time value. Time values are written to the VRML file as a double-precision floating point number in ISO C floating point format (see [ISOC]). Time values are specified as the number of seconds from a specific time origin. Typically, SFTime fields and events represent the number of seconds since Jan 1, 1970, 00:00:00 GMT.
The initial value of an SFTime eventOut is -1. The initial value of an MFTime eventOut is [ ].
Time must be written as double-precision values to represent absolute times accurately that are 20 years past the time origin. About 800 million seconds have elapsed since 1970, so an accuracy of one part in 800 million (about 1e-9) is required to represent absolute times in the present with one-second accuracy--beyond the seven digit accuracy given by single-precision floating points.
4.11 SFVec2f
and MFVec2fAn SFVec2f field or event specifies a two-dimensional (2D) vector. An MFVec2f field or event specifies zero or more 2D vectors. SFVec2f's and MFVec2f's are written to the VRML file as a pair of ISO C floating point values (see [ISOC]) separated by whitespace. For example:
fooVec2f [ 42 666, 7 94 ]
is an MFVec2f field, fooVec2f, with two valid vectors.
The initial value of an SFVec2f eventOut is (0 0). The initial value of an MFVec2f eventOut is [ ].
4.12 SFVec3f
and MFVec3fAn SFVec3f field or event specifies a three-dimensional (3D) vector. An MFVec3f field or event specifies zero or more 3D vectors. SFVec3f's and MFVec3f's are written to the VRML file as three ISO C floating point values (see [ISOC]) separated by whitespace. For example:
fooVec3f [ 1 42 666, 7 94 0 ]
is an MFVec3f field, fooVec3f, with two valid vectors.
The initial value of an SFVec3f eventOut is (0 0 0). The initial value of an MFVec3f eventOut is [ ].