Table 5.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 |
This clause describes the syntax of field data type values.
There are two general classes of fields: fields that contain a single value (where a value may be a single number, a vector, or even an image), and fields that contain an ordered list of multiple values. Single-valued fields have names that begin with SF. Multiple-valued fields have names that begin with MF.
Multiple-valued fields are written as an ordered list of values enclosed in square brackets and separated by whitespace. If the field has zero values, only the square brackets ("[ ]") are written. The last value may optionally be followed by whitespace. 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 ]
The SFBool field specifies a single boolean value encoded as either
the string TRUE or the string FALSE. For example,
fooBool FALSE
is an SFBool field, fooBool, defining a FALSE value.
The SFColor field specifies one RGB (red-green-blue) colour
triple. MFColor specifies zero or more RGB triples. Each colour is encoded as an RGB triple of floating point numbers in ISO C floating
point format (see 2.[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 SFFloat field specifies one single-precision floating point
number. MFFloat specifies zero or more single-precision floating point numbers.
SFFloats and MFFloats are encoded as ISO C floating
point format (see 2.[ISOC]). For example:
fooFloat [ 3.1415926, 12.5e-3, .0001 ]
is an MFFloat field, fooFloat, containing three floating point values.
The SFImage field specifies a single uncompressed 2-dimensional pixel image. SFImage fields are encoded 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 SFInt32 field specifies one 32-bit integer. The MFInt32
field specifies zero or more 32-bit integers. SFInt32 and MFInt32
fields are encoded 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 SFNode field specifies a VRML node. The MFNode field 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 field may contain the keyword NULL to indicate that it is empty.
The SFRotation field specifies one arbitrary rotation. The
MFRotation field specifies zero or more arbitrary rotations. An
SFRotation is encoded as four ISO C floating
point values (see 2.[ISOC]) separated
by whitespace. For example,
an SFRotation containing a PI radians rotation about the Y axis is:
fooRot 0.0 1.0 0.0 3.14159265
The SFString and MFString fields contain strings formatted with the UTF-8 universal character set (see 2.[UTF8]). SFString specifies a single string. The MFString specifies zero or more strings. Strings are encoded 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 SFTime field specifies a single time value. The MFTime field specifies zero or more time values. Time values are encoded as a double-precision floating point number in ISO C floating point format (see 2.[ISOC]). For example:
fooTime 0.0
is an SFTime field, fooTime, representing a time of 0.0 seconds.
The SFVec2f field specifies a two-dimensional (2D) vector. An
MFVec2f field specifies zero or more 2D vectors. SFVec2f's and
MFVec2f's are encoded as a pair of ISO C floating
point values (see 2.[ISOC]) separated
by whitespace. For example:
fooVec2f [ 42 666, 7 94 ]
is an MFVec2f field, fooVec2f, with two valid vectors.
The SFVec3f field specifies a three-dimensional (3D) vector.
An MFVec3f field specifies zero or more 3D vectors. SFVec3f's and
MFVec3f's are encoded as three ISO C floating point
values (see 2.[ISOC]) separated by
whitespace. For example:
fooVec3f [ 1 42 666, 7 94 0 ]
is an MFVec3f field, fooVec3f, with two valid vectors.