Brought to you by the

6.1 Introduction

6.2 SFBool

6.3 SFColor and MF Color

6.4 SFFloat and MFFloat

6.5 SFImage

6.6 SFInt32 and MFInt32

6.7 SFNode and MFNode

6.8 SFRotation and SFRotation

6.9 SFString and MFString

6.10 SFTime

6.11 SFVec2f and MFVec2f

6.12 SFVec3f and MFVec3f

6.1 Introduction

This annex describes the syntax and general semantics of fields and events, the elemental data types used by VRML nodes to define objects (see "Node Reference"). Nodes are composed of fields and events (see "Concepts - Nodes, Fields, and Events"). The types defined in this annex 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 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 a series of values enclosed in square brackets, and separated by whitespace (e.g. commas). If the field or event has zero values then only the square brackets ("[ ]") are written. The last value may optionally be followed by whitespace (e.g. comma). If the field has exactly one value, the brackets may be omitted and just the value written. 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 ]

6.2 SFBool

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.

6.3 SFColor/MFColor

SFColor specifies one RGB (red-green-blue) color triple, and MFColor specifies zero or more RGB triples. Each color is written to file as an RGB triple of floating point numbers in ANSI C floating point format, 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 colors red, green, and blue.

The initial value of an SFColor eventOut is (0 0 0). The initial value of an MFColor eventOut is [ ].

6.4 SFFloat/MFFloat

SFFloat specifies one single-precision floating point number, and MFFloat specifies zero or more single-precision floating point numbers. SFFloats and MFFloats are written to file in ANSI C floating point format. For example:

    fooFloat [ 3.1415926, 12.5e-3, .0001 ]

is an MFFloat field, fooFloat, containing three floating point values values.

The initial value of an SFFloat eventOut is 0.0. The initial value of an MFFloat eventOut is [ ].

6.5 SFImage

The SFImage field or event defines a single uncompressed 2-dimensional pixel image. SFImage fields and events are written to file as three integers representing the width, height and number of components in the image, followed by width*height hexadecimal values representing the pixels in the image, separated by whitespace:

     fooImage <width> <height> <num components> <pixels values>

A one-component image specifies one-byte hexadecimal values representing the intensity of the image. For example, 0xFF is full intensity, 0x00 is no intensity. A two-component image puts the intensity in the first (high) byte and the alpha (opacity) in the second (low) byte. Pixels in a three-component image have the red component in the first (high) byte, followed by the green and blue components (0xFF0000 is red). Four-component images put the alpha byte after red/green/blue (0x0000FF80 is semi-transparent blue). A value of 0x00 is completely transparent, 0xFF is completely opaque.

Each pixel is read as a single unsigned number. For example, a 3-component pixel with value 0x0000FF may also be written as 0xFF 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. And:

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

6.6 SFInt32/MFInt32

The SFInt32 field and event specifies one 32-bit integer, and the MFInt32 field and event specifies zero or more 32-bit integers. SFInt32 and MFInt32 fields and events are written to 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 [ ].

6.7 SFNode/MFNode

The SFNode field and event specifies a VRML node, and 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 [ ].

6.8 SFRotation/MFRotation

The SFRotation field and event specifies one arbitrary rotation, and the MFRotation field and event specifies zero or more arbitrary rotations. S/MFRotations are written to file as four floating point values 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. For example, an SFRotation containing a 180 degree rotation about the Y axis is:

    fooRot 0.0 1.0 0.0  3.14159265

The initial value of an SFRotation eventOut is (0 0 1 0). The initial value of an MFRotation eventOut is [ ].

6.9 SFString/MFString

The SFString and MFString fields and events contain strings formatted with the UTF-8 universal character set (ISO/IEC 10646-1:1993, http://www.iso.ch/cate/d18741.html). SFString specifies a single string, and the MFString specifies zero or more strings. Strings are written to file as a sequence of UTF-8 octets enclosed in double quotes (e.g. "string").

Due to the drastic changes in Korean Jamo language, the character set of the UTF-8 will be based on ISO 10646-1:1993 plus pDAM 1 - 5 (including the Korean changes). The text strings are stored in visual order.

Any characters (including newlines and '#') may appear within the quotes. To include a double quote character within the string, precede it with a backslash. To include a backslash character within the string, type two backslashes. For example:

    fooString [ "One, Two, Three", "He said, \"Immel did it!\"" ]

is a MFString field, fooString, with two valid strings.

The initial value of an SFString eventOut is "". The initial value of an MFRotation eventOut is [ ].

6.10 SFTime/MFTime

The SFTIme field and event specifies a single time value, and the MFTime field and event specifies zero or more time values. Time values are written to file as a double-precision floating point number in ANSI C floating point format. 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 [ ].

6.11 SFVec2f/MFVec2f

An SFVec2f field or event specifies a two-dimensional vector. An MFVec2f field or event specifies zero or more two-dimensional vectors. SFVec2fs and MFVec2fs are written to file as a pair of floating point values separated by whitespace. For example:

    fooVec2f [ 42 666, 7, 94 ]

is a 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 [ ].

6.12 SFVec3f/MFVec3f

An SFVec3f field or event specifies a three-dimensional vector. An MFVec3f field or event specifies zero or more three-dimensional vectors. SFVec3fs and MFVec3fs are written to file as three floating point values separated by whitespace. For example:

    fooVec3f [ 1 42 666, 7, 94, 0 ]

is a 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 [ ].

Contact rikk@best.com , cmarrin@sgi.com, or gavin@acm.org with questions or comments.

This document's URL: http://vrml.sgi.com/moving-worlds/spec/part1/fieldsRef.html