4.1 Introduction and table of contents

4.1.1 Introduction

This clause describes key concepts in this part of ISO/IEC 19775. This includes how the X3D constructs defined in ISO/IEC 19775-1 are encoded.

4.1.2 Table of contents

See Table 4.1 for the table of contents for this clause.

4.1.3 Conventions used

The following conventions are used throughout this part of ISO/IEC 19776:

Italics are used for event and field names, and are also used when new terms are introduced and equation variables are referenced.

A fixed-space font is used for URL addresses and source code examples. ISO/IEC 19776 Classic VRML encoding examples appear in bold, fixed-space font.

Node type names are appropriately capitalized (e.g., "The Billboard node is a grouping node..."). However, the concept of the node is often referred to in lower case in order to refer to the semantics of the node, not the node itself (e.g., "To rotate the billboard...").

The form "0xhh" expresses a byte as a hexadecimal number representing the bit configuration for that byte.

Throughout this part of ISO/IEC 19776, references are denoted using the "x.[ABCD]" notation, where "x" denotes which clause or annex the reference is described in and "[ABCD]" is an abbreviation of the reference title. For example, 2.[ABCD] refers to a reference described in clause 2 and B.[ABCD] refers to a reference described in annex B.

4.2 Overview

An X3D file is structured as defined in 7.2.3, Abstract X3D structure in ISO/IEC 19775-1 (see 2.[I19775-1]). This part of ISO/IEC 19776 specifies a syntax that satisfies the requirements specified by ISO/IEC 19775-1.

4.3 Classic VRML encoding file syntax

4.3.1 Classic VRML encoding

This clause describes the syntax of Classic VRML-encoded, human-readable X3D files. A more formal description of the syntax may be found in Annex A, Grammar definition. The syntax of X3D in terms of the Classic VRML encoding are presented in this part of ISO/IEC 19776. The semantics of X3D are as defined in ISO/IEC 19775-1 (see 2.[I19775-1]).

For the UTF-8 encoding, the # character begins a comment. The first line of the file, the header, also starts with a "#" character. Otherwise, all characters following a "#", until the next line terminator, are ignored. The only exception is within double-quoted SFString and MFString fields where the "#" character is defined to be part of the string.

Commas, spaces, tabs, linefeeds, and carriage-returns are separator characters wherever they appear outside of string fields. Separator characters and comments are collectively termed whitespace.

An X3D document server may strip comments and extra separators including the comment portion of the header line from an X3D file before transmitting it. WorldInfo nodes as defined in 10.4.5, WorldInfo, in ISO/IEC 19775-1 (see 2.[I19775-1]) should be used for persistent information such as copyrights or author information.

Field, event, PROTO, EXTERNPROTO, and node names shall not contain control characters (0x0-0x1f, 0x7f), space (0x20), double or single quotes (0x22: ", 0x27: '), sharp (0x23: #), comma (0x2c: ,), period (0x2e: .), brackets (0x5b, 0x5d: []), backslash (0x5c: \) or braces (0x7b, 0x7d: {}). Further, their first character shall not be a digit (0x30-0x39), plus (0x2b: +), or minus (0x2d: -) character. Otherwise, names may contain any ISO 10646 character encoded using UTF-8. X3D is case-sensitive; "Sphere" is different from "sphere" and "BEGIN" is different from "begin."

The following reserved keywords shall not be used for field, event, PROTO, EXTERNPROTO, or node names:

• COMPONENT
• DEF
• EXPORT
• EXTERNPROTO
• FALSE
• IMPORT
• IS
• META
• NULL
• PROFILE
• PROTO
• ROUTE
• TO
• TRUE
• USE
• inputOnly
• outputOnly
• inputOutput
• initializeOnly
• eventIn (deprecated name for inputOnly fields)
• eventOut (deprecated name for outputOnly fields)
• exposedField (deprecated name for inputOutput fields)
• field (deprectated name for initializeOnly fields)

4.3.2 Statements

4.3.2.1 Organization of statements

After the required Header statement as defined in 4.3.2.2, Header statement, an X3D file shall contain one PROFILE statement as defined in 4.3.2.3, PROFILE statement followed by zero or more COMPONENT statements as defined in 4.3.2.4, COMPONENT statement followed by zero or more META statements as defined in 4.3.2.5 META statement.

After the configuration information defined by the preceding paragraph, an X3D file may contain any combination of the following:

1. Any number of PROTO or EXTERNPROTO statements as defined in 4.4.3, Prototype semantics, and 4.4.4, External prototype semantics, of ISO/IEC 19775-1 (see 2.[I19775-1]);
2. Any number of root node statements as specified in 4.3.2, Root nodes of ISO/IEC 19775-1 (see 2.[I19775-1]);
3. Any number of USE statements as specified in 4.4.3, DEF/USE semantics of ISO/IEC 19775-1 (see 2.[I19775-1]);
4. Any number of ROUTE statements as specified in 4.4.7.2, Routes, of ISO/IEC 19775-1 (see 2.[I19775-1]).

4.3.2.2 Header statement syntax

Every Classic VRML-encoded X3D file shall begin with:

#X3D V3.0 utf8 [optional comment]<line terminator>

The header is a single line of UTF-8 text identifying the file as an X3D file and identifying the encoding type and profile of the file. It may also contain additional semantic information. There shall be exactly one space separating "#X3D" from "V3.0" , "V3.0" from "<encoding type>", and <encoding type> from <profile>. Also, the "<encoding type>" shall be followed by a linefeed (0x0a) or carriage-return (0x0d) character, or by one or more space (0x20) or tab (0x09) characters followed by any other characters, which are treated as a comment, and terminated by a linefeed or carriage-return character.

The identifier "utf8" indicates a clear text encoding that allows for international characters to be displayed in this part of ISO/IEC 19776 using the UTF-8 encoding defined in ISO/IEC 10646-1 (otherwise known as Unicode); see 2.[I10646-1]. The usage of UTF-8 is detailed in 15, Text component, of ISO/IEC 19775-1 (see 2.[I19775-1]) .

4.3.2.3 PROFILE statement syntax

A PROFILE statement consists of the word PROFILE followed by the name of any of the standardized profiles:

    PROFILE <profileName>

Profiles are discussed in 4.6, Profiles, of ISO/IEC 19775-1 (see 2.[I19775-1]).

See A.2, General, for details on PROFILE statement grammar rules.

4.3.2.4 COMPONENT statement syntax

A COMPONENT statement consists of the COMPONENT followed by a component support indication as follows:

    COMPONENT <componentName>:<supportLevel>

The support level is an integer identifying one of the available support levels specified in the various component clauses of ISO/IEC 19775-1 (see 2.[I19775-1]) or new clauses specified in additional parts of ISO/IEC 19775. Components are discussed in 4.5, Components, of ISO/IEC 19775-1.

See A.2, General, for details on COMPONENT statement grammar rules.

4.3.2.5 META statement syntax

A META statement consists of META followed by a string identifier for the metadata and a string containing the value of the metadata as follows:

    META <key> <value>

The three parts of the META statement shall be separated by white space. Both <key> and <value> are quoted strings that may contain any UTF-8 character.

See A.2, General, for details on META statement grammar rules.

4.3.2.6 Node statement syntax

A node statement consists of an optional name for the node followed by the node's type and then the body of the node. A node is given a name using the keyword DEF followed by the name of the node. The node's body is enclosed in matching braces ("{ }"). Whitespace shall separate the DEF, name of the node, and node type, but is not required before or after the curly braces that enclose the node's body. See A.3, Nodes, for details on node grammar rules.

    [DEF <name>] <nodeType> { <body> }

A node's body consists of any number of field statements, IS statements, ROUTE statements, PROTO statements or EXTERNPROTO statements, in any order.

4.3.2.7 Field statement syntax

A field statement consists of the name of the field followed by the field's value(s). The following illustrates the syntax for a single-valued field:

    <fieldName> <fieldValue>

The following illustrates the syntax for a multiple-valued field:

    <fieldName> [ <fieldValues> ]

See A.4, Fields, for details on field statement grammar rules.

Each node type defines the names and types of the fields that each node of that type contains. The same field name may be used by multiple node types. See 5, Field and event reference of ISO/IEC 19775-1 (see 2.I19775-1]), for the specification of field types.

4.3.2.8 PROTO statement syntax

A PROTO statement consists of the PROTO keyword, followed in order by the prototype name, prototype interface declaration, and prototype definition:

    PROTO <name> [ <declaration> ] { <definition> }

See A.2, General, for details on prototype statement grammar rules.

A prototype interface declaration consists of field declarations (see 4.3.4, Field statement syntax) enclosed in square brackets. Whitespace is not required before or after the brackets.

Field declarations consist of the keyword "field" followed by a field type, a name, and an initial field value of the given field type.

    field <fieldType> <name> <initial field value>

4.3.2.9 IS statement syntax

The body of a node statement that is inside a prototype definition may contain IS statements. An IS statement consists of the name of a field, exposedField, eventIn or eventOut from the node's public interface followed by the keyword IS followed by the name of a field, exposedField, eventIn or eventOut from the prototype's interface declaration:

    <field/eventName> IS <field/eventName>

See A.3, Nodes, for details on prototype node body grammar rules.

4.3.2.10 EXTERNPROTO statement syntax

An EXTERNPROTO statement consists of the EXTERNPROTO keyword followed in order by the prototype's name, its interface declaration, and a list (possibly empty) of double-quoted strings enclosed in square brackets. If there is only one member of the list, the brackets are optional.

    EXTERNPROTO <name> [ <external declaration> ] URL or [ URLs ]

See A.2, General, for details on external prototype statement grammar rules.

4.3.2.11 USE statement syntax

A USE statement consists of the USE keyword followed by a node name:

    USE <name>

See A.2, General, for details on USE statement grammar rules.

4.3.2.12 ROUTE statement syntax

A ROUTE statement consists of the ROUTE keyword followed in order by a node name, a period character, a field name, the TO keyword, a node name, a period character, and a field name. Whitespace is allowed but not required before or after the period characters:

    ROUTE <name>.<field/eventName> TO <name>.<field/eventName>

See A.2, General, for details on ROUTE statement grammar rules.

4.4 Classic VRML encoded X3D files and the World Wide Web

4.4.1 File extension and MIME types

The file extension for UTF-8 encoded X3D files is .wrl (for world).

4.4.2 Scripting language protocols

The Script node's url field may also support custom protocols for the various scripting languages. For example, a script url prefixed with ecmascript: shall contain ECMAScript source, with line terminators allowed in the string. The details of each language protocol are defined in the respective part for each language of ISO/IEC 19777 (see 2.[I19777]). The following example illustrates the use of mixing custom protocols and standard protocols in a single url field (order of precedence determines priority):

    #X3D V3.0 utf8 
    Script {
        url [ "ecmascript: ...",           # custom protocol ECMAScript<
              "http://bar.com/foo.js",     # std protocol ECMAScript
              "http://bar.com/foo.class" ] # std protocol Java platform bytecode
    }

In the example above, the "..." represents in-line ECMAScript source code.