1.2. Fields

1.2. Fields
	Chapter 1. Overview of VRML

1.2. Fields

Every VRML node has a set of fields. A field has a name, a type, and a default value. For example, Sphere node has a field named radius, of type SFFloat, that has a default value of 1.0.

1.2.1. Field types

There are many field types defined by VRML specification. Each field type specifies a syntax for field values in VRML file, and sometimes it specifies some interpretation of the field value. Example field types are:

SFFloat, SFDouble, SFTime

A float value. Syntax is identical to the syntax used in various programming languages, for example 3.1415926 or 12.5e-3.

X3D added SFDouble type, which should be stored and processed with at least double precision.

And there's the SFTime field type. It's syntax and internals are equivalent to SFDouble, but it has an added semantic: it specifies a time period or a point in time. In the latter case, this is the number of seconds passed since the Unix epoch (00:00:00 UTC on 1 January 1970). Although for single-player games, where time is not necessarily tied to the real-world time, sometimes other interpretations are useful, see my “VRML / X3D time origin considered uncomfortable” article.

SFLong (in VRML 1.0), SFInt32 (in VRML 2.0)

A 32-bit integer value. As you can see, the name was changed in VRML 2.0 to indicate clearly the range of allowed values.

SFBool

A boolean value. Syntax: one word, either FALSE or TRUE. Note that VRML is case-sensitive. In VRML 1.0 you could also write the number 0 (for FALSE) or 1 (for TRUE), but this additional syntax was removed from VRML 2.0 (since it's quite pointless).

SFVec2f, SFVec3f, SFVec4f

Vector of 2, 3 or 4 floating point values. Syntax is to write them as a sequence of SFFloat values, separated by whitespace. The specification doesn't say how these vectors are interpreted: they can be positions, they can be directions etc. The interpretation must be given for each case when some node includes a field of this type.

The 4-component SFVec4f was added in X3D. X3D also added double-precision versions of these vectors: SFVec2d, SFVec3d, SFVec4d.

SFColor, SFColorRGBA (X3D)

Syntax of SFColor is exactly like SFVec3f, but this field has a special interpretation: it's an RGB (red, green, blue) color specification. Each component must be between 0.0 and 1.0. For example, this is a yellow color: 1 1 0.

X3D adds also 4-component type SFColorRGBA, that adds alpha (opacity) value to the RGB color.

SFRotation

Four floating point values specifying rotation around an axis. First three values specify an axis, fourth value specifies the angle of rotation (in radians).

SFMatrix3f (X3D), SFMatrix3d (X3D), SFMatrix4f (X3D), SFMatrix4d (X3D), SFMatrix (VRML 1.0)

3x3 and 4x4 matrix types, in single or double precision. Especially useful when transferring matrix data to GPU shaders.

VRML 1.0 had also a type named just SFMatrix, this was equivalent to X3D's SFMatrix4f.

SFImage

This field type is used to specify image content for PixelTexture node in VRML 2.0 (Texture2 node in VRML 1.0). This way you can specify texture content directly in VRML file, without the need to reference any external file. You can create grayscale, grayscale with alpha, RGB or RGB with alpha images this way. This is sometimes comfortable, when you must include everything in one VRML file, but beware that it makes VRML files very large (because the color values are specified in plain text, and they are not compressed in any way). See VRML specification for exact syntax of this field.

An alternative, often better method to “inline” some file content inside VRML/X3D file is to use the data: URI. This allows you to inline file contents everywhere where normallny URI is accepted (for example, you can use normal ImageTexture and it's url field), so it's more general solution. It's also more standard (not specific to VRML/X3D at all). And it allows to place compressed data (e.g. compressed PNG, JPG or any other file format, as specified by the mime type inside URI). Although compressed data will have to be encoded in base64, so it's not storage-optimal, but still it's usually much better than SFImage non-compressed format.

The data: URI is supported by most modern VRML/X3D browsers (including every program using our engine). So it's usually preferred over using SFImage, for all but the tiniest images.

SFString

A string, enclosed in double quotes. If you want to include double quote in a string, you have to precede it with the backslash (\) character, and if you want to include the backslash in a string you have to write two backslashes. For example:

  "This is a string."

  "\"To be or not to be\" said the man."

  "Windows filename is
     c:\\3dmodels\\tree.wrl"

Note that in VRML 2.0 this string can contain characters encoded in utf8 ^[2].

SFNode

This is a special VRML 2.0 field type that contains other node as it's value (or a special value NULL). More about this in Section 1.3, “Children nodes”.

All names of field types above start with SF, which stands for “single-value field”. Most of these field types have a counterpart, “multiple-value field”, with a name starting with MF. For example MFFloat, MFLong, MFInt32, MFVec2f and MFVec3f. The MF-field value is a sequence of any number (possibly zero) of single field values. For example, MFVec3f field specifies any number of 3-component vectors and can be used to specify a set of 3D positions.

Syntax of multiple-value fields is:

An opening bracket ([).
A list of single field values separated by commas (in VRML 1.0) or whitespaces (in VRML 2.0). Note that in VRML 2.0 comma is also a whitespace, so if you write commas between values your syntax is valid in all VRML versions.
A closing bracket (]). Note that you can omit both brackets if your MF-field has exactly one value.

1.2.2. Placing fields within nodes

Each node has a set of fields given by VRML specification. VRML file can specify value of some (maybe all, maybe none) node's fields. You can always leave the value of a field unspecified in VRML file, and it always is equivalent to explicitly specifying the default value for given field.

VRML syntax for specifying node fields is simple: within node's braces ({ and }) place field's name followed by field's value.

1.2.3. Examples

Let's see some examples of specifying field values.

Sphere node has a field named radius of type SFFloat with a default value 1.0. So the file below is exactly equivalent to our first sphere example in previous section:

#VRML V1.0 ascii

Sphere {
  radius 1
}

And this is a sphere with radius 2.0:

#VRML V1.0 ascii

Sphere {
  radius 2
}

Here's a VRML 2.0 file that specifies a cylinder that should be rendered without bottom and top parts (thus creating a tube), with a radius 2.0 and height 4.0. Three SFBool fields of Cylinder are used: bottom, side, top (by default all are TRUE, so actually we didn't have to write side TRUE). And two SFFloat fields, radius and height, are used.

Remember that in VRML 2.0 we can't just write the Cylinder node. Instead we have to use the Shape node. The Shape node has a field geometry of type SFNode. By default, value of this field is NULL, which means that no shape is actually defined. We can place our Cylinder node as a value of this field to correctly define a cylinder.

#VRML V2.0 utf8

Shape {
  geometry Cylinder {
    side TRUE
    bottom FALSE
    top FALSE
    radius 2.0
    height 10.0
  }
}

Figure 1.3. Cylinder example, rendered in wireframe mode (because it's unlit, non-wireframe rendering would look confusing)

Here's a VRML 2.0 file that specifies two points. Just like in the previous example, we had to use a Shape node and place PointSet node in it's geometry field. PointSet node, in turn, has two more SFNode fields: coord (that can contain Coordinate node) and color (that can contain Color node). Coordinate node has a point field of type MFVec3f — these are positions of defined points. Color node has a color field of type MFColor — these are colors of points, specified in the same order as in the Coordinate node.

Note that PointSet and Color nodes have the same field name: color. In the first case, this is an SFNode field, in the second case it's an MFVec3f field.

#VRML V2.0 utf8

Shape {
  geometry PointSet {
    coord Coordinate { point [ 0 -2 0, 0 2 0 ] }
    color Color { color [ 1 1 0, 0 0 1 ] }
  }
}

Figure 1.4. VRML points example: yellow point at the bottom, blue point at the top

^[2]But also note that our engine doesn't support utf8 yet. In particular, when rendering Text node, the string is treated as a sequence of 8-bit characters in ISO-8859-1 encoding.


Chapter 1. Overview of VRML		1.3. Children nodes