5 Field reference

5.1 Introduction

5.1.1 Table of contents

5.1 Introduction
5.1.1 Table of contents
5.1.2 Description
5.2 SFBool
5.3 SFColor and MFColor
5.4 SFFloat and MFFloat
5.5 SFImage
5.6 SFInt32 and MFInt32
5.7 SFNode and MFNode
5.8 SFRotation and MFRotation
5.9 SFString and MFString
5.10 SFTime and MFTime
5.11 SFVec2f and MFVec2f
5.12 SFVec3f and MFVec3f

5.1.2 Description

This clause describes the syntax and general semantics of fields, the elemental data types used by VRML nodes to define objects (see 6, Node reference). Nodes are composed of fields whose types are defined in this clause (see 4, Concepts).

There are two general classes of field types: field types that contain a single value (where a value may be a single number, a vector, or even an image), and field types that contain an ordered list of multiple values. Single-valued field types have names that begin with SF. Multiple-valued field types have names that begin with MF.

Multiple-valued fields are written as an ordered list of values. If the field has zero values, the value is empty but still represented.

5.2 SFBool and MFBool

The SFBool field specifies a single Boolean value. The MFBool field specifies multiple Boolean values. Each Boolean value represents either TRUE or FALSE. How these values are represented is encoding dependent.

The initial value of an unitialized SFBool field is FALSE. The initial value of an unitialized MFBool field is the empty list.

5.3 SFColor and MFColor

The SFColor field 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 the range 0.0 to 1.0.

The initial value of an unitialized SFColor field is (0 0 0). The initial value of an unitialized MFColor field is the empty list.

5.4 SFFloat and MFFloat

The SFFloat field specifies one single-precision floating point number. MFFloat specifies zero or more single-precision floating point numbers. SFFloats and MFFloats are represented in a VRML file as specified in the respective encoding.

The initial value of an unitialized SFFloat field is 0.0. The initial value of an MFFloat field is the empty list.

5.5 SFImage and MFImage

The SFImage field specifies a single uncompressed 2-dimensional pixel image. SFImage fields contain 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.

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.

The initial value of an SFImage eventOut is (0 0 0). The initial value of an MFImage field is the empty list.

5.6 SFInt32 and MFInt32

The SFInt32 field specifies one 32-bit integer. The MFInt32 field specifies zero or more 32-bit integers. SFInt32 and MFInt32 fields are signed integers.

The initial value of an unitialized SFInt32 field is 0. The initial value of an MFInt32 field is the empty list.

5.7 SFNode and MFNode

The SFNode field specifies a VRML node. The MFNode field specifies zero or more nodes.

The initial value of an unitialized SFNode field is NULL. The initial value of an MFNode field is the empty list.

5.8 SFRotation and MFRotation

The SFRotation field specifies one arbitrary rotation. The MFRotation field specifies zero or more arbitrary rotations. An SFRotation is written to the VRML file as four floating point values. The allowable form for a floating point number is defined in the specific encoding. 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.

The 3x3 matrix representation of a rotation (x y z a) is

    [ tx²+c    txy+sz    txz-sy
      txy-sz   ty²+c     tyz+sx
      txz+sy   tyz-sx    tz²+c  ]

    where c = cos(a), s = sin(a), and t = 1-c

The initial value of an uninitialized SFRotation field is (0 0 1 0). The initial value of an MFRotation field is the empty list.

5.9 SFString and MFString

The SFString and MFString fields contain strings encoded with the UTF-8 universal character set (see 2.[UTF8]). SFString specifies a single string. The MFString specifies zero or more strings. Strings are specified as a sequence of UTF-8 octets.

Any characters (including linefeeds and '#') may appear within the string.

The initial value of an unitialized SFString eventOut is the empty string. The initial value of an MFString field is the empty list.

5.10 SFTime and MFTime

The SFTime field specifies a single time value. The MFTime field specifies zero or more time values. Time values are specified as a double-precision floating point number. The allowable form for a double precision floating point number is defined in the specific encoding. Time values are specified as the number of seconds from a specific time origin. Typically, SFTime fields represent the number of seconds since Jan 1, 1970, 00:00:00 GMT.

The initial value of an uninitialized SFTime field is -1. The initial value of an MFTime field is the empty list.

5.11 SFVec2f and MFVec2f

The SFVec2f field specifies a two-dimensional (2D) vector. An MFVec2f field specifies zero or more 2D vectors. SFVec2f's and MFVec2f's are represented as a pair of floating point values. The allowable form for a floating point number is defined in the specific encoding.

The initial value of an uninitialized SFVec2f field is (0 0). The initial value of an MFVec2f field is the empty list.

5.12 SFVec3f and MFVec3f

The 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 represented as a pair of floating point values. The allowable form for a floating point number is defined in the specific encoding.

The initial value of an uninitialized SFVec3f field is (0 0 0). The initial value of an MFVec3f field is the empty list.