Extensible 3D (X3D) encodings
Part 1: Extensible Markup Language (XML) encoding
4 Concepts
4.1 Introduction and table of contentsThis clause describes key concepts in this part of ISO/IEC 19776. This includes how the X3D Architecture constructs defined in ISO/IEC 19775-1 X3D Architecture are encoded using the Extensible Markup Language (XML) (see XML).
Design for all of the X3D file encodings (this document, ISO/IEC 19776-2 X3D Classic VRML encoding, and so forth in ISO/IEC 19776 series) and X3D programming-language bindings (ISO/IEC 19776 series) includes full expressive power for the X3D Architecture ISO/IEC 19775-1 X3D Architecture.
Table 4.1 lists the topics for this clause.
Editors note: work under review has matched corresponding organization found in
19776-1 XML Encoding Concepts
and
19776-2 Classic VRML Encoding Concepts.
Unchanged prose in this document is not highlighted if it is only moved.
Consistent document structure will further assist in the similar creation of
future X3D Encoding specifications (e.g. JSON, Turtle).
Table 4.1 — Topics in this clause
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.
Normative references and informative Bibliography entries are linked via document identifiers.
EXAMPLE
Functional requirements are defined by
ISO/IEC 19775-1 X3D Architecture.
TODO follow this pattern throughout.
With the exception of International Standards, throughout this part of ISO/IEC 19776, references to external documents are denoted using the “x.[ABCD]” notation, where "x" denotes in which clause or annex the reference is described and “[ABCD]” is an abbreviation of the reference title. References without the "x." are references to the bibliography. International Standards are referenced by their number and link to the appropriate entry in 2 Normative references.
EXAMPLE [ABCD] refers to a reference described in Clause 2 and [ABCD] refers to a reference described in the Bibliography. TODO: fix, distinguish [ABCD] references
see Mantis 1125
TODO Remove "x." notation, express clearly. Remove [square brackets] from all references.
Follow form shown in ISO Directives Part 2, section 15.5.3 Referencing, using "ISO/IEC".
Identifiers can be used in the hyperlinks.
4.2 OverviewA valid XML file is also known as an XML document. An X3D file is structured as defined by 7.2.5 Abstract X3D structure in the X3D Architecture ISO/IEC 19775-1 X3D Architecture. When expressed using this part of ISO/IEC 19776, it also meets all requirements defined by the Extensible Markup Language (XML) (see XML).
The Extensible Markup Language (XML) (see XML) is used for a self-validating X3D encoding of Extensible 3D (X3D) Graphics. This X3D encoding provides a Web-compatible format that maximizes interoperability with other Web languages. XML supports structuring data, is similar to HTML, is readable by systems and humans, is verbose for clarity, represents a modular family of technologies, and is fundamentally interoperable with Web technologies. See XML10 for more background information.
There is a fundamental and complete correspondence between the elements of the abstract X3D scene graph and constructs in the XML encoding. The X3D XML Encoding has full expressive power for all scene constructs defined by the X3D Architecture ISO/IEC 19775-1 X3D Architecture. This section describes the design patterns that govern the correspondence.
An X3D file
that uses X3D XML encoding must first include XML and model header information,
as described in
4.2.3 Header section.
(the following block was moved here from original 4.3.2 Statements)
After the required statements as defined in 4.2.3.1 File descriptor, X3D version, character encoding, and XML validation, an X3D file shall contain:
After the model configuration information defined by the preceding paragraph, required XML header and <X3D> document-root tag, an X3D file may contain any combination of the following:
Within the X3D document root tag is the optional header section, and the required scene body.
The following example shows shows a minimal but complete X3D model. shows the XML header followed by head, Scene and related elements.
EXAMPLE 2 XML syntax for a complete X3D model.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 4.0//EN" "https://www.web3d.org/specifications/x3d-4.0.dtd">
<X3D version='4.0' version='3.3' profile='Immersive'
xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance'
xsd:noNamespaceSchemaLocation='https://www.web3d.org/specifications/x3d-4.0.xsd'>
<head>
<component name='Geospatial' level='1'/>
<component name='NURBS' level='2'/>
<unit category='length' conversionFactor='0.01' name='Centimeters'/>
<meta name='description' content='X3D scene header and prototype syntax examples.'/>
<meta name='title' content='X3dHeaderPrototypeSyntaxExamples.x3d'/>
<meta name='identifier'
content='https://web3d.org/x3d/content/examples/Basic/development/X3dHeaderPrototypeSyntaxExamples.x3d'/>
</head>
<Scene>
<!-- Scene graph nodes are added here -->
</Scene>
</X3D>
This example header indicates that the content is XML using the UTF-8 character encoding, matches X3D version 4.0, 3.3, follows the Immersive Profile, and explicitly lists additional expected components. The X3D header may also contain further semantic information, using meta statements tags for name='metadataTerm' and content='value' pairs. Note that the third meta tag should not break in the middle of the string.
Header sections appear near the top of an X3D file to properly identify the file encoding, along with X3D version and profile information, thus enabling correct parsing to commence upon initial file loading. Additional information is also provided regarding document-specific information such as necessary components, unit conversions of numeric base types, and name=value pairs for document-specific metadata.
The header section for every XML-encoded X3D file shall begin with a file-description line, which is a single line of UTF-8 text identifying the file as an XML file, followed by the XML declaration that identifies the validating XML DTD, followed by X3D tags that identify the validating XML Schema, X3D profile, and (optionally) the necessary additional components of the file. Explanatory details follow.
For easy identification of X3D files, every XML-encoded X3D file shall begin with an XML file declaration (see XML).
<?xml version="1.0" encoding="UTF-8"?>
The identifier "UTF-8" indicates a clear text character encoding that allows for international characters to be displayed in X3D using the UTF-8 encoding defined in ISO/IEC 10646 Universal Coded Character Set (UCS). The character encoding "UTF-16" is also a permitted.
The XML header is immediately followed by an XML DOCTYPE statement which provides both PUBLIC and SYSTEM literals for the X3D XML Document Type Definition (DTD) (see XML).
The X3D DOCTYPE declaration is as follows:
<!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 4.0//EN" "https://www.web3d.org/specifications/x3d-4.0.dtd">
<!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 3.3//EN" "http://www.web3d.org/specifications/x3d-3.3.dtd">
In addition As an alternative to DTD validation, XML Schema validation can be performed through identification of XML Schema and X3D namespaces within the root X3D tags as defined in XML_SCHEMA XML_NAMESPACES .
EXAMPLE 2 1 XML Schema validation syntax for an X3D model.
<X3D profile='Immersive' version='4.0'
xmlns:xsd='https://www.w3.org/2001/XMLSchema-instance'
xsd:noNamespaceSchemaLocation='https://www.web3d.org/specifications/x3d-4.0.xsd'>
<X3D profile='Immersive' version='3.3'
xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance'
xsd:noNamespaceSchemaLocation='http://www.web3d.org/specifications/x3d-3.3.xsd'>
Both DOCTYPE and schema declaration are optional.
A DOCTYPE or schema declaration is optional.
The reference DTD and location
is specified in this document. To allow for extensible tag sets (supersets of
the base specification), authors may point to a document definition other than
the ones listed in this specification. However, the alternate definition shall
specify an equivalent document to the base X3D DTD/Schema (i.e., the tag
instances shall look exactly the same regardless of the source DTD schema).
Authors shall use the X3D DOCTYPE and/or X3D Schema extension mechanisms to add
validation capability for new nodes and fields.
This completes most of the XML header information, but necessary further details follow.
Next comes the required X3D document root element tag that specifies version and profile information with optional schema validation information (including xsd namespace and XML schema url).
The top-level X3D element includes a required profile attribute that contains the name of any of the profiles specified in ISO/IEC 19775-1 X3D Architecture.
EXAMPLE
<X3D version='4.0' profile='Immersive'>
The component element includes a required name attribute that contains the name identifier of any of the components specified in ISO/IEC 19775-1 X3D Architecture, along with a required level attribute that defines the corresponding level of interest.
EXAMPLE
<component name='Sound' level='3'/>
The unit element includes a required category attribute that contains the name of one of the four base unit categories specified in ISO/IEC 19775-1 X3D Architecture Table 4.2, with an author-defined name attribute for identification purposes, and a conversionFactor attribute that defines a positive double-precision value that can be multipled to convert model units into corresponding X3D base units. All three attributes are required.
EXAMPLE
<unit category='length' conversionFactor='0.01' name='Centimeters'/>
The meta element includes a required name attribute that contains the name of any of the components specified in ISO/IEC 19775-1 X3D Architecture, along with a required level attribute that defines the corresponding level of interest.
This clause describes the syntax of XML-encoded, human-readable X3D files. The syntax of X3D in terms of the XML encoding are presented in this part of ISO/IEC 19776. The semantics of X3D are as defined in ISO/IEC 19775-1 X3D Architecture. Rules for parsing and handling XML-encoded documents are defined in XML.
Two formal grammar descriptions of the XML syntax for X3D may be found in Annex A X3D XML Document Type Definition (DTD) and Annex B X3D XML Schema. These grammars are directly implementable by XML parsers.
X3D nodes and statements are represented as XML elements. Parent-child relationships between nodes are directly represented in the XML tree structure.
Attribute values may be delimited by identical paired single-quote (') or double-quote (") characters. Neither authors nor parsers can guarantee which kind types of paired delimiting characters might be encountered when processing an XML file, is encountered since intermediate XML processors are allowed to independently choose either form (single-quote or double-quote). These rules are described in XML and XML_INFOSET . which take precedence over all rules in this clause.
XML elements (i.e., X3D nodes and X3D statements) (e.g., X3D nodes) may not appear within XML attribute values.
Space characters, Spaces, tabs, linefeeds, and carriage-returns are separator characters wherever they appear outside of XML attribute values. Separator characters are collectively termed whitespace. Commas are not ignorable whitespace when mixed between XML elements or element and attribute values.
Within X3D attribute values, the rules are slightly different. Commas, spaces, tabs, linefeeds, and carriage-returns are separator characters wherever they appear outside of XML attribute values. Separator characters and comments are collectively termed whitespace.
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 character encoded using UTF-8, as defined in ISO/IEC 10646 Universal Coded Character Set (UCS). ISO 10646 character encoded using UTF-8.
X3D is case sensitive; "Sphere" is different from "sphere" and "BEGIN" is different from "begin".
In order to maintain interoperable conversion capabilities translatability between the various file encodings and programming-language bindings for X3D models, different X3D encodings of X3D scenes, the following reserved keywords shall not be used for field, event, prototype or node names:
(prior prose moved to 4.2.2 The structure of an X3D file)
It is important to note that X3D statements are distinct from X3D nodes and X3D fields, with separate semantics as defined by the ISO/IEC 19775-1 X3D Architecture.
The profile attribute along with the component, unit, and meta elements are described in 4.2.3 Header section subclauses above. All X3D statements are expressed syntactically as XML elements with corresponding XML attributes. Examples are shown in Encoding of statements.
A Prototype declaration consists of the ProtoDeclare keyword, followed in order by the prototype name attribute, optional prototype interface field declarations contained within a ProtoInterface, and required prototype body definition contained within a ProtoBody.
Prototype field statements consist of the field keyword, followed in any order by the attribute values for field name, field type and field accessType (having value inputOnly, outputOnly, initializeOnly or inputOutput).
EXAMPLE 1 Prototype declaration examples (without and with field declarations, respectively):
<ProtoDeclare name='NewWorldInfoNode'>
<!-- Prototype declarations are not required to have field declarations -->
<ProtoBody>
<WorldInfo DEF='ExamplePrototypeBody' title='Hello New World Intro'/>
</ProtoBody>
</ProtoDeclare>
<ProtoDeclare name='EmissiveMaterial'>
<ProtoInterface>
<field name='onlyColor'
type='SFColor'
accessType='inputOutput'/>
</ProtoInterface>
<ProtoBody>
<!-- Override default diffuseColor value 0.8 0.8 0.8 -->
<Material diffuseColor='0 0 0'>
<!-- Connect emissiveColor field of current node to onlyColor field of parent ProtoDeclare. -->
<IS>
<connect nodeField='emissiveColor' protoField='onlyColor'/>
</IS>
</Material>
</ProtoBody>
</ProtoDeclare>
A field statement also contains the default value of the field when the accessType is either initializeOnly or inputOutput. Simple values are contained in the value attribute (e.g., value='true'). If the default value of an SFString or MFString field is empty, the default value may be omitted. Node (or node array) values are contained as child nodes within the field declaration.
The <Group DEF='DefaultNodeValue'/> in the following example provides a default initialization for the children field declared in the ProtoDeclare body.
EXAMPLE 2 X3D prototype definition using XML ProtoDeclare syntax.
<ProtoDeclare name='ShiftGroupUp2m'>
<ProtoInterface>
<field name='children'
type='MFNode'
accessType='inputOutput'>
<Group DEF='DefaultNodeValue' bboxSize='2 2 2'/>
</field>
</ProtoInterface>
<ProtoBody>
<Transform translation='0 2 0'>
<Group>
<IS>
<connect nodeField='children'
protoField='children'/>
</IS>
</Group>
</Transform>
</ProtoBody>
</ProtoDeclare>
The same field name may be used independently by multiple prototype instances node prototypes.
See 5 Encoding of fields for the specification of the XML encoding of each X3D field type.
The body of a node statement that is inside a prototype definition may optionally contain a single <IS> statement, which in turn contains one or more <connect> statements. Each <connect> statement consists of a nodeField attribute with the name of a field from the parent node's interface, followed by a protoField attribute with the name of a field from the ancestor ProtoDeclare. When defined in a scene, any contained <IS> element shall be the first child element within a node definition, with two exceptions. Script, ComposedShader, PackagedShader, and ShaderProgram nodes include field definitions before IS/connect. ProtoInstance definitions include fieldValue initializations before IS/connect.
The type and accessType of each field shall match exactly. These nodeField and protoField names may be overloaded; i.e., these two names may be identical since each is part of a different namespace.
Example IS/connect constructs are included in the prototype declaration examples provided by 4.3.7 Prototype and field declaration syntax.
ISO/IEC 19775-1 X3D Architecture (see 4.4.4 Prototype semantics) specifies ISO/IEC 19775-1 X3D Architecture for details on external prototype statements.
An ExternProtoDeclare statement consists of the ExternProtoDeclare element, a name attribute for the referenced Prototype, and a url of one or more addresses referring to the scene defining this Prototype. Zero or more contained field definitions then follow to provide the interface for the prototype.
Contained field statements consist of the field keyword, followed in any order by the attribute values for field name, field type and field accessType (inputOnly, outputOnly, initializeOnly and inputOutput).
url values are "quote delimited" local filenames and/or remote addresses. Each filename or address should have a pound # symbol appended, followed by the case-sensitive literal name of the externally defined Prototype node. (This url syntax is similar to HTML bookmarks and X3D Anchor viewpoint links.)
EXAMPLE An external prototype declaration: follows:
<ExternProtoDeclare
name='ViewPositionOrientation'
nodeType='Viewpoint'
url='"ViewPositionOrientationPrototype.x3d#ViewPositionOrientation"
"https://www.myorg.org/examples/ViewPositionOrientationPrototype.x3d#ViewPositionOrientation"
"ViewPositionOrientationPrototype.wrl#ViewPositionOrientation"
"https://www.myorg.org/examples/ViewPositionOrientationPrototype.wrl#ViewPositionOrientation"' >
<field name='enabled'
type='Boolean'
accessType='inputOutput'/>
</ExternProtoDeclare>
See 4.4.5 External prototype semantics in ISO/IEC 19775-1 X3D Architecture for details on external prototype statements.
A ROUTE statement consists of a ROUTE element followed by attributes fromNode, fromField, toNode and toField. The fromNode and toNode attributes are of XML type IDREF, meaning that corresponding DEF values shall be found in the preceding nodes.
The following semantic restrictions apply:
EXAMPLE The following illustrates ROUTE statement syntax:
<TimeSensor DEF='Clock' cycleInterval='4' loop='true'/>
<OrientationInterpolator
DEF='Spinner'
key='0 0.5 1'
keyValue='0 1 0 0,0 1 0 3.1416, 0 1 0 6.2832'/>
<ROUTE fromNode='Clock' fromField='fraction'
toNode='Spinner' toField='set_fraction'/>
<ROUTE fromNode='Spinner' fromField='value_changed'
toNode='TransformExampleUSE' toField='rotation'/>
The following XML syntax applies to the EXPORT/IMPORT IMPORT/EXPORT functionality of X3D.
An EXPORT statement consists of an EXPORT element followed by attributes localDEF and (optionally) AS.
EXAMPLE 1 2 The following depicts the XML encoding of an EXPORT statement within the inlined InlineExport.x3d model:
<!-- file InlineExport.x3d -->
<Transform DEF='T1'> <!-- contained 3D content --> </Transform>
<!-- Hint: EXPORT statement follows node of interest, since localDEF field is similar to USE with type IDREF -->
<EXPORT localDEF='T1' AS='RootTransform'/>
An IMPORT statement consists of an IMPORT element followed by attributes inlineDEF, importedDEF, exportedDEF, and (optionally) AS.
EXAMPLE 2 1 The following depicts the XML encoding of an IMPORT statement within a parent scene that corresponds to a separate Inline model:
<!-- file InlineImport.x3d -->
<Inline DEF='MyInlineModel' url='"InlineExport.x3d"' DEF='I1' url='"someUrl.x3d"'/>
<IMPORT
inlineDEF='MyInlineModel' inlineDEF='I1'
importedDEF='RootTransform' exportedDEF='RootTransform'
AS='MyInlineRootTransform' AS='I1Root'/>
<OrientationInterpolator DEF='MySpinner' key='0 0.3333 0.6667 1'
keyValue='0 1 0 0, 0 1 0 2.094395, 0 1 0 4.18879, 0 1 0 0'/>
<ROUTE
fromNode='MySpinner' fromField='value_changed'
toNode='MyInlineRootTransform' toNode='I1Root' toField='set_rotation'/>
This section summarizes how X3D models are encoded in accordance with the Extensible Markup Language (XML) (see XML).
X3D nodes are expressed as XML elements (i.e., tagged names).
Simple non-node X3D fields are expressed as XML attributes in the form of name="value" pairs.
Nodes which serve as fields to other X3D nodes are expressed as contained XML elements, i.e. additional tagged names. Each child element includes an implicit (default) or explicitly defined containerField attribute whose value equals the field name. value.
A node definition statement consists of the element name type-name for the node element followed by the allowed simple-field attributes. A node instance can be given a label using the attribute DEF followed by an equals sign and the quoted name of the node.
Each tag begins and ends with angle brackets < and >, respectively. A node's body is enclosed by a pair of matching open and closing tags, where a closing tag has a slash / prepended to the element name.
EXAMPLE 1 XML declarations illustrating The followingillustrates the use of node and field syntax:
<Group DEF='ExampleChildElement'>
<Shape>
<Box/>
<Appearance>
<Material diffuseColor='0.6 0.4 0.2'/>
</Appearance>
</Shape>
</Group>
Alternatively, if no further elements are contained as child nodes, a singleton single tag may omit the closing element tag by ending the single element with /> characters.
EXAMPLE 2 Three X3D nodes as XML singleton elements, with no child elements.
<Box/>
<Viewpoint DEF='ExampleSingleElement' description='Hello syntax'/>
<NavigationInfo type='"EXAMINE" "ANY"'/>
EXAMPLE 3 Three identical X3D nodes as XML elements, using paired open and close tags, with no child elements.
<Box></Box>
<Viewpoint DEF='ExampleSingleElement' description='Hello syntax'></Viewpoint>
<NavigationInfo type='"EXAMINE" "ANY"'></NavigationInfo>
A node element contains zero or more field attributes, as appropriate for each node type. When nested inside a ProtoDeclare ProtoBody, a node's content can optionally begin with a single IS statement, which in turn contains one or more connect statements. A node then contains zero or more child nodes, ROUTE statements, ProtoDeclare statements or ExternProtoDeclare statements. These contained nodes and statements are allowed as appropriate for each node type, and can typically appear in any order.
Whitespace shall separate the name of the node and attribute="value" pairs, but is not required before or after the element tags that enclose the node's body.
See 6 Encoding of nodes for the specification of the XML encoding of each node type. XML-based scene validation for proper parent-child relationships among nodes can be performed using either the X3D XML Document Type Definition (DTD) or X3D XML Schema. The DTD and Schema also define default values for attribute fields, matching the abstract specification. Additional validation is also possible using X3D XML Schematron.
Each DEF (ID) value in a scene is a node identifier and shall be unique.
A USE attribute indicates that a node is a reference copy of a DEF node with the same ID. DEF is assigned XML type ID, and USE is assigned XML type IDREF, respectively. The same name-construction conventions regarding legal character combinations apply.
EXAMPLE 1 Correct type matches between DEF and USE nodes are valid.
<Inline DEF='MyModel' url='"MyModel.x3dv"'/>
<Inline USE='MyModel'/>
<Group DEF='SomethingCool'> <!-- cool content goes here --> </Group>
<Transform translation='0 0 1'/>
<Group USE='SomethingCool'/>
</Transform>
EXAMPLE 2 Incorrect type matches between DEF and USE nodes are invalid.
<Group DEF='SomethingCool'> <!-- cool content goes here --> </Group>
<Transform USE='SomethingCool'> <!-- erroneous node type --> </Transform>
Non-unique node DEF names for nodes in the body of ProtoDeclare definitions are allowed by the ISO/IEC 19775-1 X3D Architecture since they are in a separate namespace. However, such duplication will cause validation errors when checked by the X3D DTD or Schema. This is an XML validation constraint for single documents a limitation of XML that requires each XML DTD and Schema to have a single namespace for ID types.
Nodes being reused via a USE attribute can include no other attributes except containerField. Inclusion of the HTML-related style and class attributes are also allowed for USE nodes. Declaring modified values for other X3D fields within a USE node is not allowed, since both field definitions found in the original DEF node declaration take precedence and are simply referenced by the USE node.
EXAMPLE 3 Reusing the ExampleChildElement node declared in 4.3.3 Example 1 as a USE node: Continuing the previous example statements:
<Transform DEF='HasChildUSE' DEF='ExampleUSE'
rotation='0 1 0 0.78'
translation='0 2.5 0'>
<Group USE='ExampleChildElement' containerField='children' USE='ExampleChildElement'/>
<-- Note that this USE node is not allowed to have additional X3D fields or other child nodes -->
</Transform>
Nodes containing a USE="someName" attribute can include no other attributes except containerField and class. Default values for other fields shall be ignored since field definitions in the original DEF node declaration have precedence.
For Classic VRML interoperable conversion, note that certain characters are not allowed as DEF or USE identifiers, as specified in Annex A Grammar of ISO/IEC 19776-2 X3D Classic VRML encoding. Such characters are best avoided, especially the period character (. or 0x2E) since it is used as part of the syntax for ROUTE construction in the Classic VRML encoding.
The ProtoInstance element is used to create instances of nodes, which shall be defined previously in the scene using either ProtoDeclare or ExternProtoDeclare statements.
ProtoInstance can contain zero or more fieldValue elements which are used to provide initial values for fields defined in the corresponding predecessor ProtoDeclare or ExternProtoDeclare statement. These fieldValue initializations must be correctly typed, and are only used for field definitions with accessType of initializeOnly or inputOutput, and override any default values defined in the corresponding ProtoDeclare.
EXAMPLE 1 Two ProtoInstance instantiations with typed fieldValue initialization
<Transform translation='0 -2.5 0'>
<Shape>
<Appearance>
<ProtoInstance name='EmissiveMaterial'>
<fieldValue name='onlyColor'
value='0.2 0.6 0.6'/>
</ProtoInstance>
</Appearance>
<Text string='"Prototype syntax" "examples"'>
<FontStyle justify='"MIDDLE" "MIDDLE"'/>
</Text>
</Shape>
</Transform>
<ProtoInstance DEF='MyVPO' name='ViewPositionOrientation'>
<fieldValue name='enabled' value='true'/>
</ProtoInstance>
ProtoInstance definitions always require a valid name, even when defining a USE node. This approach permits confirmation of author intent that the correct prototype is applied.
EXAMPLE 2 ProtoInstance USE node
<ProtoInstance USE='MyVPO' name='ViewPositionOrientation'/>
Each node type defines the names and types of the fields that each node of that type contains. In general, nearly all field-node relationships are unambiguous due to the well-defined parent-child node relationships in X3D.
In order to achieve a compact tagset in the XML encoding for X3D, the name of the parent node's field field typically containing each node is accounted for by the containerField attribute. For example, Sensor nodes are typically contained by the children field of Grouping nodes, hence each Sensor node has containerField='children' as the default value.
Ordinarily the containerField value can be omitted, since multiple ambiguous child fields rarely occur. The default containerField value for a given node may be overridden when necessary to indicate a different relationship with a given node's parent.
EXAMPLE Again reusing the USE='ExampleChildElement' node (first declared with DEF in 4.3.3 Example 1 and shown with USE in 4.3.4 Example 3), this time without including the default containerField='children' attribute:
<Collision>
<Shape containerField='proxy'>
<Sphere/>
</Shape>
<Group USE='ExampleChildElement'/>
</Collision>
<!-- overriding containerField='proxy' necessary for Shape -->
<!-- default containerField='geometry' omitted from Sphere -->
<!-- default containerField='children' omitted from Collision and Group -->
Since the containerField attribute exactly matches the field name between a parent node and a child node, the containerField attribute is not an X3D field as defined in ISO/IEC 19775-1 X3D Architecture. Similarly, the containerField attribute is not found in other X3D file encodings, since they express field-name relationships between parent and child nodes differently.
For ProtoInstance USE requirements see ProtoInstance node and fieldValue statement syntax.
The class attribute is reserved for use with HTML5 and XML Cascading Style Sheets (see W3C-CSS-Snapshot). CSS).
TODO discuss purpose of cascading stylesheets, X3D Architecture Annex L HTML Guidelines
Code for scripts should not be placed so as to be parsed by XML parsers. Therefore, such code should be encapsulated to avoid such parsing. The preferred method to encapsulate source code in a Script node is to wrap it in a child CDATA construct following the <field/> and <IS><connect/></IS> definitions. The CDATA construct (see XML) ensures that all contained characters are treated literally without further escaping or modification.
If both a url field and a CDATA clause are encountered, the url field is processed first. Thus, the CDATA construct can also be considered equivalent to one additional value appended to the url MFString array. This ordering allows an online script code url to take priority over fallback default script code in the CDATA construct. This ordering also allows run-time updates if a viewer is connected to the network, if so desired by the originating author.
EXAMPLE 19 The following example demonstrates the use of a CDATA construct within a Script node:
<Script directOutput='true'>
<field name='ROOT' type='SFNode' accessType='initializeOnly'>
<Transform USE='ROOT'/>
</field>
<![CDATA[
javascript:
function R ()
{
return Math.random();
}
function initialize()
{
for (i=0; i < 10; i++)
{
rand1 = 100*R();
rand2 = 100*R();
rand3 = 20*R();
rand4 = 40*R();
rand5 = 20*R();
string =
'Transform {' +
' translation ' + rand1 + ' 0 ' + rand2 +
' children [' +
' Shape {' +
' appearance Appearance {' +
' material Material {' +
' diffuseColor ' + R() + ' ' + R() + ' ' + R() +
' }' +
' }' +
' geometry Box {' +
' size ' + rand3 + ' ' + rand4 + ' ' + rand5 +
' }' +
' }' +
' ]' +
'}';
newNode = Browser.createVrmlFromString(string);
ROOT.children[i] = newNode[0];
}
}
]]>
</Script>
Comments are often important for explaining model design or work in progress. Comments do not affect the rendering or interaction of an X3D model. Nevertheless, comments are essential information to communicate author intent, design considerations, model capabilities, and expectations for continued development. Comment functionality is described in ISO/IEC 19775-1 X3D Architecture X3D Architecture, Core component, 7.2.5.1 Organization.
In the XML encoding, the character sequences <!-- and --> delimit a comment. Only this single form for comment syntax is allowed in the X3D XML encoding, exactly matching that defined by XML. Whitespace within X3D XML comments may be normalized.
<!-- This is an X3D comment. -->
<WorldInfo/>
<!-- this is a comment between XML elements (nodes or statements) -->
<Group/>
<!-- this is another XML comment
<WorldInfo/>
<Group/>
-->
Comments may appear at any place in the XML document that is allowed by XML. Of note, with respect to X3D file structure and XML validation, comments can appear between XML elements, and also between opening tags and closing tags for a single element. However, unlike some other X3D file encodings, XML comments are not allowed to appear within simple-type field attributes.
EXAMPLE 2 Erroneous XML comment syntax.
<WorldInfo title="Error, invalid comment within an element"
<!-- XML comments are not allowed within or between attribute values -->
/>
NOTE
X3D model comments might not necessarily be preserved by intermediate processes when compressed, or when X3D files are relayed over the Web. Further, the exact placement of comments within an X3D model's structure may necessarily vary among X3D file encodings and programming language bindings. When appropriate, critical model information can also be retained in a lossless and consistently structured fashion by capturing it within META statements or the various Metadata nodes.
The only exceptions to this description of XML comments are within XML CDATA sections, which are ignored during XML parsing and typically only used for embedded script code. Comment exceptions also occur within double-quoted SFString and MFString fields, where the comment characters are escaped (using < for < and > for >) and are defined to be part of the string. TODO check correctness.
4.4 X3D files and the World Wide WebXML-encoded X3D files shall use a file extension of either “.x3d” or “.xml”. the file extension “.x3d”. The MIME-type associated with that XML-encoded X3D file is “model/x3d+xml”.
X3D-encoded X3D files that have been “gzipped” shall use a file extension of either “.x3dz” or “.x3d.gz”. The MIME type is “model/x3d+xml”. The content-encoding value is “gzip”.
The concept of MIME types is defined in RFC2077 MIME.
(TODO: description of EXI file extension and MIME)The X3D XML DTD is useful for file validation and quality assurance (QA). It is defined in Annex A X3D XML Document Type Definition (DTD).
The X3D XML schema is useful for file validation and quality assurance (QA). It is defined in Annex B X3D XML Schema.
X3D XML Schematron is useful for file validation and quality assurance (QA). It is defined in Annex C X3D XML Schematron.