This document defines the 5th revision of XML3D, an extension to HTML5 for describing interactive 3D scenes.

Introduction

Motivation

The idea of adding virtual 3D worlds to the web has a long history: In 1994, Dave Ragget proposed a platform independent 3D scene description based on web technologies as “mechanisms for people to share VR models on a global basis”. Ragget also proposed to describe the structure of the virtual world on a high abstraction level based on the experiences of SGML and HTML. In the same year, Pesce et al. proposed extending “HTML to describe both geometry and space”.

However, the developers of the resulting VRML standard decided against designing VRML as an extension to HTML. As a result, Web3D never took off until Vladimir Vukićević prototyped an OpenGL-based API for the HTML <canvas> element in 2006. This idea finally led to [[WebGL]].

Although WebGL is a great technology and paved the way for accelerated 3D graphics in the browser, it also comes with some disadvantages that are addressed by XML3D: First, it is only loosely coupled with other W3C technologies such as HTML, CSS, DOM scripting and events. As a consequence, web developers need to learn new concepts and WebGL-based libraries can not interoperate with HTML and DOM libraries such as jQuery. Secondly, WebGL is tied to OpenGL and does not take other algorithms and APIs into account. For instance, the definition of pipeline shaders is too specific and too low-level to use for ray tracing or global-illumination algorithms.

Thus, XML3D picks up the idea of a platform independent 3D scene description on a higher abstraction level on the basis of HTML (and yes, XML3D is a stupid name for that). At the same time, it takes the features of modern graphics APIs into account and exposes data processing and shading capabilities to the user, which can be mapped to the GPU pipeline. Despite these capabilities it can still be rendered with arbitrary rendering algorithms.

We do not expect that browser vendors will implement XML3D natively in the near future. The main motivation of this specification is to enable people to share their 3D assets including 3D models, materials and animations and to easily create stunning 3D web applications. Therefore, XML3D is accompanied with a reference application, a polyfill that uses WebGL and JavaScript to emulate native XML3D support. As a result, XML3D is fully usable today and various applications already exist.

However, having said that, we expect that a native implementation of XML3D would come with a series of benefits: Browsers could render scenes with advanced rendering algorithms or render the scene or parts of the scene as a service in the cloud. The higher abstraction level gives implementations opportunities to optimize performance and to provide advanced debugging facilities. A native renderer can also reason about the scene's content and changes and - as a result - driving VR applications would be much easier.

About XML3D

This specification defines the features and syntax of XML3D.

XML3D is a language for describing interactive 3D scenes. Although the name may suggest otherwise, XML3D is not an XML language. Instead it is designed as an extension to [[HTML5]]. Consequently, XML3D defines an abstract language and APIs for interacting with the 3D scene. Similar to HTML5, the concrete syntax of XML3D can be either the [[HTML5]] syntax or the [[XML]] syntax.

XML3D reuses concepts from HTML5: [[DOM]] scripting and [[UIEvents]] allow easy creation of interactive 3D scenes. [[CSS2]] can be used to define styling properties for XML3D elements such as transformations or visibility. Hence, XML3D is tightly integrated into the W3C technology stack.

On the other hand, XML3D introduces some novel concepts. XML3D introduces a generic data model to define arbitrarily named and typed parameters. XML3D has a dataflow graph concept in order to describe data processing within the HTML document. Finally, it supports programmable materials based on JavaScript. These concepts are essential to gain a higher flexibility compared to previous declarative 3D scene descriptions (e.g. VRML or X3D).

XML3D is platform independent, i.e. an XML3D scene description can be rendered using arbitrary rendering algorithms. Thus, XML3D can not only be rendered with various flavours of GPU rasterization (forward rendering, deferred rendering, etc), but also with ray tracing and rendering algorithms taking global illumination into account (e.g. Monte Carlo path tracing). Similar to HTML, XML3D describes what should be rendered rather than how it should be rendered.

XML3D is a lean low-level 3D scene description. Convenience functionality found in other approaches can be implemented on top of XML3D, for instance using scripting and concepts such as [[custom-elements]].

Compatibility with Other Standards Efforts

XML3D leverages and integrates with other W3C specifications and standards efforts. By leveraging and conforming to other standards, XML3D becomes more powerful and makes it easier for users to learn how to incorporate XML3D into their Web sites. XML3D uses [[URI]]s, in particular URNs for identifiying predefined models and URLs for identifing resources in the same or in external documents.

Concepts

Generic data model

HTML elements can be parametrized using HTML attributes or CSS properties. In graphics we need, however, the possibility to define sets of arbitrarily named and typed parameters. Additionally, these parameters may be very long, for instance the positions of a mesh. Hence, we introduce a generic data model for XML3D, which is used consistently throughout XML3D's abstract model.

XML3D's generic data model provides means to share and compose data between data consumers such as the mesh element, light element, view element, and material element. It is also the basis for the dataflow graph concept and for programmable materials with shade.js, which both require arbritraily typed and named parameters.

All data elements output a table of named entries. This table is composed
To not spoil the user experience, large parameter sets (e.g. mesh data) should never be defined inside the web page. Instead, this kind of data should be defined in external resources which are loaded asynchronously, e.g. in a JSON file or, more efficiently, using a container in Blast format.

Mark-up

The value elements can be used to define data table entries directly in mark-up. This is useful for all parameters that need to be modified during runtime using the DOM API. Value elements can be used to construct a reusable data source using the data element, or to parametrize a consumer element, e.g. a mesh element, directly.
                <data id="parameter-set">     <!-- generic data container -->
                    <float3 name="parameter-1">1.0 0.0 0.0</float3>
                    <float name="parameter-2">0.5</float>
                </data>

                <material id="material1" model="...">     <!-- parameterized consumer -->
                    <float3 name="parameter-1">1.0 0.0 0.0</float3>
                    <float name="parameter-2">0.5</float>
                </material>
          

Sequences

The generic data model allows arbitrarily long sequences of data to be defined using the key attribute on value elements. This is useful, for example, to define the base data for mesh animations to be driven by Xflow compute operators.

          <data id="keyFrameData">
            <float3 name="position" key="0" >-5 0 5 ... </float3>
            <float3 name="normal" key="0" >0 -1 0 ... </float3>

            <float3 name="position" key="0.1" >-2.886751 2.113249 2.886751 ... </float3>
            <float3 name="normal" key="0.1">-0.554395 -0.620718 0.554395 ... </float3>

            <float3 name="position" key="0.2">-1.341089 4.649148 1.341089 ... </float3>
            <float3 name="normal" key="0.2">-0.696886 0.169412 0.696886 ... </float3>

            <float3 name="position" key="0.3" >-6.158403 1.408833 6.158403 ... </float3>
            <float3 name="normal" key="0.3">-0.141341 -0.979819 0.141341 ... </float3>

            ...
          </data>
        

The above sequence of data represents the keyframes of a mesh animation. Typically a compute operator would then be used to interpolate between keyframes, or to otherwise map the sequences of data to a definite set of position and normal data to be rendered.

External resources

For external data resources, a mapping to a data table needs to be defined which is identified via the internet media type [[rfc2045]] of the resource. XML3D comes with mappings for external XML3D files, and JSON files in XML3D format. In xml3d.js, additional mappings can be provide via a plug-in mechanism.
A STL file consists of vertex positions and face normals. A mapping could define that the vertex positions are mapped to an entry named position and to per-vertex normals (requires processing) named normal, both of type float3. Then a mesh element can reference STL files directly:
        <mesh src="printable-teapot.stl"></mesh>
        
Note that defining this mapping is possible in xml3d.js via a plug-in. A plug-in for STL files is available here.

Data compositing

Data can be shared and composed from multiple internal and external sources. A set of overriding rules handles cases, where entries with the same name and sequence key exits.
  1. A subsequent value element overrides previous ones.
  2. Local value elements override referenced data sources.
  3. Entries in the output of a referenced data table override entries of a previously referenced data table.
  4. The output of a referenced data table gets evaluated with the same set of overriding rules before it is taken into account.
The overriding rules can be exploited to specialize more general data sources.
       <data id="specularTerm">
         <float3 name="specularColor">0.1 0.2 0.3</float3>
         <float name="ambientIntensity">0.1</float>
         <float name="shininess">0.2</float>
         <float name="shininess">0.6</float> <!-- shininess is 0.6 according to rule 1 -->
       </data>

       <data id="diffuseTerm">
         <float3 name="diffuseColor">0.1 0.2 0.3</float3>
         <float name="ambientIntensity">0.9</float>
       </data>

       <material id="composedMaterial"> <!-- Composing a material from multiple sources -->
         <data src="path/to/external/resource.xml#textureData"></data>
         <data src="#specularTerm"></data>  <!-- shininess is 0.6 according to rule 4 -->
         <data src="#diffuseTerm"></data>   <!-- ambientIntensity is 0.9 according to rule 3 -->

       </material>

       <material id="specializedMaterial">
         <data src="#specularTerm"></data>  <!-- Reuse data from #specularTerm -->
         <float name="shininess">0.4</float> <!-- shininess is 0.4 according to rule 2 -->
       </material>
         

Filters

The generic data model defines three filters that may be applied to data through the filter attribute on the data element and the dataflow element.

        filter="keep|remove(field1 [, field2...])"
        filter="rename( { newFieldName : field [, newFieldName2 : field2...] } )"
      

A filter does not change the data itself but rather influences how that data is made available to other elements. For example, using a remove filter does not actually remove the data from the element, it simply hides it from parent elements.

An data element may only have one filter, if multiple filters are needed they can be applied with nested data elements.

        <data filter="keep(A,D)">
          <float name="A" >0</float>
          <float name="B" >1</float> <!-- will be removed -->
          <float name="C" >1</float> <!-- will be removed -->
          <float name="D" >1</float>
        </data>

        <data filter="remove(D)">
          <float name="A" >0</float>
          <float name="B" >1</float>
          <float name="C" >1</float>
          <float name="D" >1</float> <!-- will be removed -->
        </data>

        <data filter="rename( {A2 : A, B2 : B} )">
          <float name="A" >0</float> <!-- will be renamed into A2 -->
          <float name="B" >1</float> <!-- will be renamed into B2 -->
          <float name="C" >1</float>
          <float name="D" >1</float>
        </data>

        <data filter="keep( {A2 : A, B2 : B} )">
          <float name="A" >0</float> <!-- will be renamed into A2 -->
          <float name="B" >1</float> <!-- will be renamed into B2 -->
          <float name="C" >1</float> <!-- will be removed -->
          <float name="D" >1</float> <!-- will be removed -->
        </data>

        <data filter="rename( {A1 : A, A2 : A, A3: A} )">
          <float name="A" >0</float> <!-- will be provided under the names A1, A2 and A3 -->
        </data>
      

Dataflow graph (Xflow)

XML3D comes with a lean set of scene elements, in particular if compared to other scene descriptions. To describe dynamic effects in the scene XML3D provides a dataflow graph approach (Xflow), that allows arranging data processing operations as a graph of operations. This way, it is possible to describe complex dynamic data processing from basic blocks.

Xflow is powerful enough to describe all common dynamic effects usually implemented in fixed-function entities including skinning, morphing, augmented reality functionality, etc. The basic principle of Xflow is a small addition to the general data model: It allows attaching an operator to a data element using the compute attribute. A data element with such a compute operator attached first composes the data table as usual. This data tabe is then used as the input of the compute operator. The output of the compute operator (i.e. the result) is merged with original data table. In this merge, entries from the result table override entries with the same name from the input table.

The compute operator

Compute operators can be used to change or create data inside an Xflow graph. They operate like functions, receiving a set of input arguments, doing some work and then outputting the result. On a data element an operator may be invoked through the compute attribute using the following syntax:

         compute="(output1 [,output2...]) = xflow.[operatorName]([argument1, ...])"
        

In a dataflow element one or more compute operators can be invoked inside a compute block using the compute element.

The fields listed as outputs will be added to the list of data that this data element provides. The arguments must be available to the data element that invokes the operator, either as value elements or provided by a child data element. Compute operators can be invoked in sequence by nesting data elements:

          <data compute="position = xflow.add(position, offset2)">
            <data compute="position = xflow.add(position, offset1)">
              <float3 name="position">...</float3>
              <float3 name="offset1">...</float3>
            </data>
            <float3 name="offset2">...</float3>
          </data>
        

XML3D includes several compute operators by default (a complete list may be found here) but also provides an interface to declare custom compute operators. These can be saved in their own JavaScript files and served alongside xml3d.js. Before being used a custom operator must be registered with Xflow by calling Xflow.registerOperator with the following syntax:

          Xflow.registerOperator("xflow.myOperatorName", {
            outputs: [ {type: 'float3', name: 'outputName', customAlloc=true },
                       ...
            ],

            params:  [ {type: 'int', source: 'inputName1', optional=true },
                       {type: 'float3', source: 'inputName2', array=true },
                       ...
            ],

            alloc: function(sizes [, inputName1, ...]) {
               // Only necessary if one or more outputs have the flag 'customAlloc=true'
               sizes['outputName'] = inputName2.length;
            },

            evaluate: function(outputName, inputName1, inputName2, info) {
               ...
            }
          });
        
As long as a custom operator appears after the xml3d.js script in the document flow the Xflow.registerOperator function can (and should) be called immediately. This is typical behavior for a JavaScript plugin architecture and ensures the operators have been registered before XML3D initializes the scene (during the document.onload event).

In essence the declaration of the compute operator must contain at least a list of input and output fields, including types, and an evaluate function that is called by Xflow during data processing. Input fields may be marked as optional, otherwise they will generate an error if missing.

Output fields may be allocated with a custom size, indicated with the customAlloc flag. When this flag is present Xflow will call the alloc function, which should declare the sizes of the data arrays that Xflow needs to create for these fields. If a field is not marked with customAlloc then Xflow will attempt to choose the right size based on the inputs to the compute operator.

Fields marked with the array flag will be provided to the evaluate function as is and will exclude them from the normal length-matching checks that Xflow performs on input arguments. This can be used, for example, to pass an array of data with 100 elements while the other input fields all contain thousands of elements. Normally this would generate an error as Xflow would not be able to properly iterate through the data.

The evaluate function will always be called with the list of output fields first, then the input fields, then an info object supplied by Xflow. The info object contains information about how the data can be iterated and offers a place to store data during processing:

          info = {
            iterFlag: [true|false,...], // Is the input at this position an array that should be iterated over or a single element?
            iterateCount: number,       // The number of elements in the input data to iterate over, ie. (input array length) / (tuple size)
            customData: {}              // A field to hold custom data during and between operator executions
          }
        
Fields marked with the array flag will always have an iterFlag value of false

The following is an example operator that uses the info object to iterate over a set of positions, adding a constant offset and returning the result as a new array of positions:

          Xflow.registerOperator("xflow.addOffset", {
            outputs: [ {type: 'float3', name: 'result' }
            ],

            params:  [ {type: 'float3', source: 'position' },
                       {type: 'float3', source: 'offset', array=true }
            ],

            evaluate: function(result, position, offset, info) {
               // In this example 'offset' is an array with 3 values (a single float3)
               // 'position' is an array containing thousands of values

               for (var i=0; i < info.iterateCount; i++) {
                  result[i*3] = position[ info.iterFlag[0] ? i*3 : 0 ] + offset[0];
                  result[i*3+1] = position[ info.iterFlag[0] ? i*3+1 : 1 ] + offset[1];
                  result[i*3+1] = position[ info.iterFlag[0] ? i*3+2 : 2 ] + offset[2];
               }
            }
          }
        

Style

Since XML3D extends HTML, all [[CSS2]] properties also apply to XML3D elements. However, only the semantic of a few of them make sense for the 3D scene description. In the following we list the relevant style properties that influence the rendering of the scene.
Other properties may affect XML3D elements in the future. Good candidates include the visible and pointer-events properties.

The display property

'display'
Value:   inline | block | list-item | inline-block | table | inline-table | table-row-group | table-header-group | table-footer-group | table-row | table-column-group | table-column | table-cell | table-caption | none | inherit
Initial:   inherit
Applies to:   Scene elements

The meanings of the values of this property for XML3D elements:

none
This value causes an element to not contribute to the rendering, i.e. geometry elements are not rendered, light elements do not emit light into the scene. Also, geometry elements do not generate bounding boxes (empty boxes) nor contribute to their parent's bounding box. Descendant elements do not display and do not contribute to the parents' bounding boxes either.
<other values>
All other values do not affect the rendering of the element.
A 'display' value of none will hide all descendant elements regardless of their local properties, as it does in HTML. Here are some examples for the 'display' property:
      mesh.hidden { display: none } /* do not display meshes with hidden class */
      xml3d > * > * > * > * model { display: none; } /* Hide all models deeper than the fifth hierarchy level */
    
Modifying the display property with jQuery:
      $("#myMesh").hide();
      $(".walls").toggle();
    
Be careful when assigning display: none to the xml3d element itself (or a parent of it). In HTML, elements with display: none have a width and height of 0 and this may cause XML3D to be initialized improperly.

The transform property

'transform'
Values:   translateX | translateY | translateZ | translate3d | rotateX | rotateY | rotateZ | rotate3d | scaleX | scaleY | scaleZ | scale3d | matrix3d
Initial:   identity matrix
Applies to:   Transformable elements

[[CSS3-transforms]] can be used to specify 3D transformations for any transformable element. The transform property may hold any number and combination of values, which will be combined from left to right. Transformations also apply to all descendant scene elements, building a transformation hierarchy.

CSS transitions can also be used to animate transforms. The below example smoothly moves an object from left to right:

            // Ease an object 5 units on the x axis over 500ms
            $("#myMesh").css({ transform: "translate3d(5px, 0px, 0px);", transition: "transform 500ms ease" });
        
Some transform functions (eg. translate3d) require a unit of measurement to be valid. Because browsers do not yet support units that make sense for a 3D scene these values should be given in 'px'. For example, translate3d(10px, 5px, 0px). Internally these transformations will of course be in the units that the scene uses.
Some browsers silently ignore invalid CSS transforms. If a CSS transform is not behaving as expected double check to ensure the formatting and syntax are valid.

The z-index property

'z-index'
Value:   auto | <integer>
Initial:   auto
Applies to:   Scene elements

The meanings of the values of this property for XML3D elements:

auto
This is the default value and causes the element to be rendered in the same z-layer (stacking context) as its parent element. If no other z-index values appear in the scene this means all elements will be rendered in a single z-layer according to their distance from the camera.
<other values>
Any value other than '0' will create a new stacking context, similar to the behavior of z-index for normal HTML elements.

During rendering objects will first be sorted into bins according to the stacking contexts present in the scene. Then the bins will be rendered from lowest z-index to highest, with the objects in each bin sorted according to their distance from the camera. The depth buffer will be cleared between each bin.

This has the effect of rendering objects with a higher z-index on top of those with a lower z-index regardless of their spatial orientation in the scene.

Note that the same stacking context rules apply for XML3D elements as for HTML elements. This means an element's z-index is always relative to the closest parent element having a z-index value other than 'auto'.

Here are some examples for the 'z-index' property:
        <mesh src="example.xml" style="z-index: 5"></mesh>
        <mesh src="example.xml" style="z-index: 10"></mesh> <!-- Will always be drawn above the other two meshes -->
        <mesh src="example.xml" style="z-index: -5"></mesh> <!-- Will always be drawn below the other two meshes -->
    
In the example below the mesh with the z-index value of 500 will be drawn below the other meshes. This is because both groups create their own stacking contexts, and the second group's z-index is lower than that of the first.
            <group style="z-index: 1">
                <mesh src="example.xml" style="z-index: 10"></mesh> <!-- Will always be drawn above the second mesh -->
                <mesh src="example.xml"></mesh>
            </group>
            <group style="z-index: -1">
                <mesh src="example.xml" style="z-index: 500"></mesh> <!-- Will be drawn *below* the other meshes -->
            </group>
        

The elements of XML3D

Kinds of elements

Transformable elements

assetmesh, group, mesh, model, light, view

Transformable elements are those that are able to be transformed, either through CSS3 transforms or the transform element. Not all transformable elements can be nested but when they are they build a transformation hierarchy, with the transformation matrix of each node being defined as its own local transformation matrix multiplied with the transformation matrix of its parent element.

A third possibility for defining a transformation is to reference a data element through the transform attribute instead of a transform element. This data element may either contain a single float4x4 element with name transform or use a compute operator to generate the transformation matrix.

In cases where both a CSS transform and a transform attribute are given the CSS transform will take precedence.

The following example shows four different ways of defining the same transformation on a group element.

            <!-- Using a CSS3 transform -->
            <group style="transform: translate3d(0px, 0px, 10px)"></group>

            <!-- Using a transform element -->
            <transform id="myTransformElement" translation="0 0 10"></transform>
            <group transform="#myTransformElement"></group>

            <!-- Giving the transformation matrix directly -->
            <data id="myDataTransform">
              <float4x4 name="transform">1 0 0 0 0 1 0 0 0 0 1 10 0 0 0 1</float4x4>
            </data>
            <group transform="#myDataTransform"></group>

            <!-- Computing the transformation matrix with an Xflow operator -->
            <data id="myComputeTransform" compute="transform = xflow.createTransform(translation)">
              <float3 name="translation">0 0 10</float3>
            </data>
            <group transform="#myComputeTransform"></group>
          

Data elements

assetdata, data, dataflow, mesh, material, model, light

Data elements are the non-leaf nodes of an Xflow graph. They may contain any combination of data elements and value elements. They may also reference other data elements through the src attribute using a standard HTML URI.

The ultimate function of a graph of data elements is to provide data to a "sink". Some data sinks in XML3D include the mesh element, the material element and the projection attribute of the view element.

The ability to reference data elements makes it possible to share a common set of data between many different sinks. This saves memory and increases performance, as the data is also shared internally whenever possible. For example, a set of vertex positions may be shared between many instances of the same mesh using a different set of face indices each time. Internally these meshes will also share a common WebGL vertex position buffer:

              <data id="shared_positions">
                <float3 name="position"> 1.0 0.0 0.0 0.5 1.0 1.0 ... </float3>
              </data>
              <mesh>
                <data src="#shared_positions"></data>
                <int name="index"> 0 1 2 3 4 5 ... </int>
              </mesh>
              <mesh>
                <data src="#shared_positions"></data>
                <int name="index"> 3 4 5 0 1 2 ... </int>
              </mesh>
          

If two data elements containing fields with identical names are present in an XFlow data graph then the outermost value will replace any value nested deeper within the graph. In this example the value of the color field will be 1.0 0.0 0.0 when referencing #my-data:

              <data id="my-data">
                  <float3 name="color">1.0 0.0 0.0</float3> <!-- Overrides the nested color -->
                  <data>
                      <float3 name="color">1.0 1.0 1.0</float3>
                  </data>
              </data>
         

Value elements

float, float2, float3, float4, float4x4, int, int4, bool, texture

Value elements are the leaf nodes of an Xflow graph. They may not be nested and may not contain any non-text child elements. Data should be provided as a text node containing a space-separated list of values. The tag name determines how this data is interpreted:

              <bool>1 0 0</bool>     // an array of three boolean values
              <float3>1 0 0</float3> // a single three-dimensional floating point vector
          

The name attribute of a value element acts as an ID for the data contained in this element. It may be referenced in XFlow operators or in material shaders.

If two value elements with the same name are present inside a data element then the value appearing later in the DOM will be used. In this example the value of the color field will be 1.0 1.0 1.0 when referencing #my-data:

                <data id="my-data">
                    <float3 name="color">1.0 0.0 0.0</float3>
                    <float3 name="color">1.0 1.0 1.0</float3> <!-- Overrides the previous color -->
                </data>
          

Pickable elements

mesh, model

Pickable elements are the drawable geometries of a scene. These elements can trigger mouse events like most visible HTML elements do, we call this picking. The list of available mouse event listeners is described in the Events section.

Mouse events will also bubble up through the scene hierarchy, which allows mouse event listeners to also be placed on the group element and the xml3d element. Listeners on these elements can only be triggered by a pickable element (model or mesh) in the element's subtree.

When the user interacts with an object on the canvas (eg. clicks on it) the relevant MouseEvent will be generated on the mesh element or model element and then bubbled up the scene hierarchy. This will continue until the event reaches the xml3d element, or until event.stopPropagation() is called.

In the following example, when clicking on the object in the scene corresponding to this mesh element both listeners will be triggered in the appropriate order:

            <group onmousedown="myMouseDownListener(event)">
                <group>
                    <mesh onmouseup="myMouseUpListener(event)" type="triangles"></mesh>
                </group>
            </group>
           
Object visibility may affect whether or not mouse event listeners are triggered. See the Style section on visibility for more information.

The root element

The xml3d element

The xml3d element is the root element of an XML3D scene. It will create a canvas element at this position in the DOM to display the rendered scene. CSS styles and event listeners from the XML3D element are also applied to the canvas allowing for mouse interaction with the XML3D scene.

A page may have more than one XML3D element, in this case multiple canvases with their own WebGL contexts will be created. It is also possible to share date elements between scenes in which case XML3D will automatically create the necessary WebGL buffers for each context.

Because XML3D uses HTML ids to reference elements it is important to avoid duplicate ids. For example, a duplicate id for a data element that appears in two different XML3D scenes on the same page may lead to undefined behavior.

The view attribute, if present, must contain a selector that returns a view element as first matching element using querySelector on the xml3d element. The selection mechanism is described in the Selectors API [[selectors-api2]]. If the attribute is not present, or if the selector does not return a valid view element, the selector view is used instead, returning the first view in the scene. If no view is available, the system must append a view element as first child of the xml3d element.

The background color of the 3D canvas may be set through CSS using the background-color property on the xml3d element.

attribute unsigned long width
Horizontal dimension
attribute unsigned long height
Vertical dimension
readonly attribute boolean complete
Returns true if all resources of the root element have been completely downloaded and rendered; otherwise, returns false.
attribute DOMString view
The view IDL attribute must reflect the respective content attribute of the same name.
attribute Function onframedrawn
Event listener to be executed whenever a new frame has been drawn. Is passed a FrameDrawn event.
attribute Function onload
Event listener to be executed when the xml3d element has finished loading. This event is fired once after initial loading of the scene is complete, including all external resources such as textures or external models. It will not be fired again if subsequent changes to the scene cause more resources to be loaded. When adding a listener for this event through JavaScript it may be necessary to check the status of the complete attribute beforehand, as the load event will not be resent if it was already dispatched before the listener was registered.
This event may be preceeded by one or more FrameDrawn events as XML3D continues to redraw the scene even as external resources are being loaded.
HTMLElement? getElementByPoint()
Returns the element at the point with window coordinates x,y if there is a scene element; otherwise, returns null.
unsigned long x
The x coordinate relative to the top left of the browser window
unsigned long y
The y coordinate relative to the top left of the browser window
optional Vec3 hitPoint
If provided this vector will be filled with the position of the hit point in world space.
optional Vec3 hitNormal
If provided this vector will be filled with the normal of the hit point in world space.
HTMLElement? getElementByRay()
Returns the first element that intersects with the ray if the ray intersects with a scene element; otherwise, returns null. Unlike getElementByPoint this function is not dependent on the currently active view. This makes it useful for, for example, finding the surface normal of an object at a particular point regardless of whether or not that object is currently visible to the active camera.
Ray ray
optional Vec3 hitPoint
If provided this vector will be filled with the position of the hit point in world space.
optional Vec3 hitNormal
If provided this vector will be filled with the normal of the hit point in world space.
Box getLocalBoundingBox()
Returns the bounding box of the scene. Because the XML3D element is the root element the bounding box will be in world space by definition.
Box getWorldBoundingBox()
Returns the bounding box of the scene in world space.
Ray generateRay()
Uses WebGL unProject to generate a new ray from the given x,y window coordinates.
unsigned long x
The x coordinate relative to the top left of the browser window
unsigned long y
The y coordinate relative to the top left of the browser window

Scene elements

The group element

Categories:
Transformable element

The group element is a non-leaf node in an XML3D scene tree. They can be used to build transformation hierarchies and to group renderable objects together. Groups can be nested, but because they are not Xflow elements they may not hold any data elements and cannot be referenced by other group elements. This means that unlike data elements, groups build a tree structure rather than a graph. Each group may only have a single parent.

Group elements inherit properties such as transformations, visibility and materials from their parent group.

            <group style="display: none;" material="#blueMaterial">
                <group style="display: block;">
                    <!-- This mesh will not be visible but will inherit #blueMaterial -->
                    <mesh type="triangles"></mesh>
                </group>
            </group>
        
attribute DOMString transform
Accepts a URI fragment referencing a transform element. Alternatively a transformation may be defined with CSS through the style attribute.
attribute DOMString material
Accepts a URI fragment referencing a material element. Material is inherited from the parent group if this attribute is not present.
Mat4 getWorldMatrix()
Returns the transformation matrix of this group element in world space (includes parent transformations).
Mat4 getLocalMatrix()
Returns the local transformation matrix of this group element (does not include parent transformations).
Box getLocalBoundingBox()
Returns the bounding box of this group in its local transformation space. This is calculated as the smallest volume containing the bounding boxes of all child elements.
Box getWorldBoundingBox()
Returns the bounding box of this group in world space. This is calculated as the smallest volume containing the bounding boxes of all child elements.

The view element

Categories:
Data element
Transformable element

The view element defines a viewport into the scene. The view (or camera) model that defines the projection of the scene to the XML3D canvas is defined by the model attribute. The view uses the generic data model to define the parameters of the referenced view model (aka intrinsic camera parameters). The coordinate system of the view element defines the coordinate system for the view (aka extrinsic camera parameters).

The view model used by the view is defined by the view model attribute. If the model attribute is present, it must contain a valid non-empty URN referencing one of the predefined view models. If the URN is empty or references an unknown view model, or if the model attribute is not present, the perspective view model is used.

Currently, XML3D supports predefined view models only. However, similar to materials, we envisage programmable view models for future versions of XML3D.

This example illustrates the use of a view based on the predefined perspective view model using its default parameters:

        <view></view>
       
It defines a perspective frustum that conforms to the right-handed rules and points along the negative z-axis. In the following example, the default direction is altered using CSS Transformations. Additionally, the perspective frustum has a different vertical field-of-view:
        <view style="transform: rotate3d(0, 1, 0, 180deg);">
          <float name="fovVertical">0.5</float>
        </view>
       

This example illustrates the use of a projective view model using a custom projection matrix:

        <view model="urn:xml3d:view:projective">
          <float4x4 name="projectionMatrix">1.4485281705856323 0 0 0 0 2.4142134189605713 0 0 0 0 -9.523809432983398 -1 0 0 -94.18809509277344 0</float4x4>
        </view>
       
XML3D does not provide camera navigation through the scene by e.g. binding mouse events to changes to the active view element. Instead, this is left to the application (or some navigation library), because the navigation is part of the interaction with the scene and is typically very application-specific.
attribute DOMString model
The model IDL attribute must reflect the model content attribute.
Mat4 getWorldMatrix()
Returns the transformation matrix of this view element in world space.
Mat4 getLocalMatrix()
Returns the local transformation matrix of this view element (does not include parent transformations).
Mat4 getViewMatrix()
Returns the view matrix of the camera (the matrix used to transform from world to view space).
Mat4 getProjectionMatrix()
Returns the projection matrix for the frustum defined by this view.

The light element

Categories:
Data element
Transformable element

The light element defines a light source in the scene that emits light based on the light model defined by the model attribute. The light uses the generic data model to define the parameters of the referenced light model. The coordinate system of the light element defines the base coordinate system for the light. However, the final position and direction of the light source can altered by specific parameters of the light model.

A light affects all geometry elements within the same scene, i.e. with the same xml3d element as ancestor.

The light model used by the light is defined by the model attribute. If the model attribute is present, it must contain a valid non-empty URN referencing one of the predefined light models. If the URN is empty or references an unknown light model, or if the model attribute is not present, the directional light model is used.

Currently, XML3D supports predefined light models only. However, similar to materials, we envisage programmable light models for future versions of XML3D.

This example illustrates the use of a single light source based on the predefined directional light model using its default parameters:

        <light></light>
       
Since no direction for the light source is specified for the light source, the default direction 0 0 -1 (along the negative z axis) is transformed by the global coordinate system of the light element.

This example illustrates the use of a single light source based on the predefined point light model:

        <light model="urn:xml3d:light:point">
          <float3 name="intensity">0.8 0.8 1</float3>
        </light>
       
attribute DOMString model
The model IDL attribute must reflect the model content attribute.
Mat4 getWorldMatrix()
Returns the transformation matrix of this light element in world space.
Mat4 getLocalMatrix()
Returns the local transformation matrix of this light element (does not include parent transformations).

The mesh element

Categories:
Data element
Pickable element
Transformable element

The mesh element represents a single renderable object in the scene. To be drawn correctly a mesh must either inherit a material from a parent element or assign its own through the material attribute. The type attribute determines how the mesh data is interpreted to be drawn and must be one of the predefined primitive types.

A mesh can only be assigned a single material. Models that contain multiple materials will have to be broken down into separate meshes.

The simplest way to define a mesh is to include its data directly in the mesh element:

            <mesh type="triangles" material="#myMaterial">
                <int name="index">0 1 2 ... </int>
                <float3 name="position">1.0 0.0 0.0 ... </float3>
                <float3 name="normal">0.0 1.0 0.0 ... </float3>
            </mesh>
        

However it's usually a good idea to reference this data instead, either in the same document or in an external document as shown below:

            <!-- myDataElement is the id of a data element containing the mesh data -->
            <mesh src="myMesh.xml#myDataElement" type="triangles" material="#myMaterial"></mesh>
        

Each entry in the mesh data is passed on to the material shader in the form of a vertex attribute. A mesh must always supply at least a position entry, any others are optional but may be required by a material in order to be rendered properly (eg. normal in conjunction with the predefined phong material).

As with any data element, a mesh may override certain entries or supply its own. This applies even to material entries:

            <!-- This mesh will be rendered with a blue diffuseColor even though the material specifies a red one -->
            <mesh src="myMesh.xml#myDataElement" type="triangles" material="#myRedMaterial">
                <float3 name="diffuseColor">0.0 0.0 1.0</float3>
            </mesh>
        

The mesh type can also be set using the generic attribute system, setting the mesh type to derived

            <!-- The mesh data will be interpreted as lines -->
            <mesh src="teapot.json" type="derived">
                <string name="type">lines</string>
            </mesh>
        

Different ways of assigning transformations to meshes are described in the transformable elements section.

readonly attribute boolean complete
Returns true if all external resources required by this mesh have been loaded, false otherwise.
attribute DOMString type
The primitive type that this mesh uses. Supported values are triangles, tristrips, points, lines, linestrips and derived.
attribute DOMString src
URI reference to another data element containing the data for this mesh. Can be a reference to an external document.
attribute DOMString material
URI reference to a material element.
attribute DOMString transform
URI reference to a transform element.
XML3DDataResult getResult(Array filter)
Returns a XML3DDataResult object containing the data for the fields requested by the given filter, eg. ["position", "index", "normal"]. This is useful for accessing the mesh data directly through JavaScript.
Array getOutputNames()
Returns the names of the data fields available to this mesh node.
Mat4 getWorldMatrix()
Returns the transformation matrix of this mesh element in world space (includes parent transformations).
Mat4 getLocalMatrix()
Returns the local transformation matrix of this mesh element (does not include parent transformations).
Box getLocalBoundingBox()
Returns the bounding box of this mesh in object space, without any transformations applied.
Box getWorldBoundingBox()
Returns the bounding box of this mesh in world space.

The model element

Categories:
Data element
Pickable element
Transformable element

The model element is used to instantiate an asset. This is useful for rendering complex objects with many individual meshes or materials. Not only is it easier to insert a single model element into the DOM, it's also much more efficient.

When referencing an external file the URI must contain the id of the asset element to be instantiated:

            <model src="myExternalAsset.xml#myAsset"></model>
          

A model may override data inside the Asset by specifying the assetmesh element or assetdata element that should be overwritten. For example, to change the material of a mesh inside the Asset named "hat" we would define our model tag as follows:

            <model src="myExternalAsset.xml#myAsset">
               <assetmesh name="hat" material="#aNewMaterialDefinedLocally"></assetmesh>
            </model>
          
Materials inside the asset will always override those assigned to the model. To assign a material from outside the asset either remove all inner materials entirely or override each assetmesh individually as shown above.
This behavior is especially useful in driving animations inside the instantiated asset. Each instance of the model element can have its own animation state, even if all reference the same asset. Typically this is done by exposing the animation key through its own assetdata, which is then overwritten in the model:
            <!-- Assuming "myAsset" contains an assetdata element with name "animation" -->
            <model src="myExternalAsset.xml#myAsset">
               <assetdata name="animation">
                <float id="animation_key" name="key">1.0</float>
              </assetdata>
            </model>
          
By changing the value of the animation_key through JavaScript we can now control the model's animation state.
attribute DOMString src
URI reference to an asset element that this model should instantiate.
attribute DOMString material
URI reference to a material element. This material will only be used for objects that do not define their own material inside the asset.
attribute DOMString transform
URI reference to a transform element.
Mat4 getWorldMatrix()
Returns the transformation matrix of this model in world space, including parent transformations.
Mat4 getLocalMatrix()
Returns the local transformation matrix of this model element (does not include parent transformations).
Box getLocalBoundingBox()
Returns the bounding box of this model without any parent transformations applied.
Box getWorldBoundingBox()
Returns the bounding box of this model in world space, including parent transformations.

Definition Areas

The defs element

The defs element is simply an organizational tool to separate the scene tree from elements that are not explicitly part of the scene, but may be referenced by elements that are. These implicit elements include transform, material, data and dataflow. Note that any of these elements may appear inside the scene tree as well, it's just good practice to keep them in the defs section whenever possible.

Ideally the only elements that should appear outside the defs section are group, mesh, model, view and light. Note that these elements will be ignored if they are inside the defs section, since it is not considered part of the scene tree. data elements usually belong in the defs section but may also be part of the scene tree if contained by a mesh element.
          <xml3d>
            <defs>
               <transform id="myTransform" rotation="0 1 0 0.75">
               <data id="myMeshData" >
                  <float3 name="position">1.0 0.0 0.0 ...</float3>
               </data>
            </defs>

            <group transform="#myTransform">
               <mesh src="#myMeshData" type="triangles"></mesh>
            </group>
          </xml3d>
        

Property elements

The material element

Categories:
Data element

A material describes the surface shading of an object. Materials are defined using the material element and then referenced by the material property on a given scene element to indicate that the given element shall be shaded using the referenced material. Multiple scene elements can share a material. The material uses the generic data model to define the parameters of the referenced material model. Note that graphics elements can override the parameters defined in the material element. Hence, the parameters in the material element can be considered default values.

The material model used by the material is defined by the material model attribute. The model attribute must be present, and must contain a valid non-empty URL referencing either a predefined material model or a scripted material model, e.g. using shade.js or a custom shader.

Here is a simple example for a material based on the predefined phong material model:

        <material model="urn:xml3d:material:phong">
          <float3 name="diffuseColor">0 0 1</float3>
          <texture name="diffuseTexture">
            <img src="../stone.jpg"/>
          </texture>
        </material>
       
attribute DOMString model
The model IDL attribute must reflect the model content attribute.

The transform element

In addition to CSS3 transformations applied through the style attribute, the transform element provides another way to define transformations for transformable elements. The various transformation components are combined into a transformation matrix which is then applied to the element or elements referencing this transform element.

Transform elements are generally placed into the defs section of a scene, however it's possible to define them anywhere inside the xml3d element. No matter where a transform element is defined it must be referenced by its id from the transform attribute of a transformable element to be used. A single transform element can be referenced by multiple other elements.

attribute AxisAngle scaleorientation
The orientation on which to apply the scaling factor supplied by the IDL attribute scale. In axis-angle form [x,y,z,a] with the angle expressed in radians.
attribute AxisAngle rotation
The rotation component of this transformation. In axis-angle form [x,y,z,a] with the angle expressed in radians.
attribute Vec3 translation
The translation component of this transformation.
attribute Vec3 scale
The scale component of this transformation. Note: non-uniform scaling and negative values are allowed.
attribute Vec3 center
The center point of this transformation.

Assets

The XML3D asset format is designed to encompass everything needed to define a complex model consisting of one or more meshes and materials. Conceptually an asset is designed to be static and self-enclosed. When referenced from a model element an asset behaves as a single object in the scene, even though it may be composed of many different meshes. Interaction through mouse event listeners, for example, can only be done on the model level and not on the level of individual meshes comprising the asset.

As with other Xflow elements most parts of the asset (eg. materials, mesh data, transformations) can be overridden inside the model element. However it's important to note that adding or removing overrides for assets has a very high performance penalty. Best practice is to define all the necessary overrides during construction of the model element and then stick to changing the values of those overrides, which carries no performance penalty. See the XML3D Wiki for more information on how to override asset data.

It's important to note that unlike a group and mesh hierarchy, assets are always flattened. An asset always consists of an asset element with a list of assetmesh elements as children, which cannot be nested. Asset elements themselves, on the other hand, can be nested.

The asset element

The asset element defines an asset that can be instantiated through a model element or extended by another asset. The asset element also defines a scope for the name and includes attributes of any child assetdata and assetmesh elements.

Asset elements may be nested but their id must be unique within the document.

attribute DOMString src
A URI to another asset that this one should extend.

The assetdata element

Categories:
Data element

Similar to the data element an assetdata element is used to define and share generic data within an asset. Unlike data elements, assetdata elements may not be nested and are named by and referenced through a name attribute rather than an id. An assetdata element may contain normal data elements as children.

Assetdata names must be unique within an asset element.

attribute DOMString name
The name of this assetdata element. The name is scoped to the surrounding asset element and may not be duplicated within this scope.
attribute DOMString includes
A space separated list of names corresponding to other assetdata elements that this one should extend.

The assetmesh element

Categories:
Data element
Transformable element

An assetmesh element represents a single drawable mesh in the asset and works similar to the mesh element. Unlike the mesh element assetmeshes are identified by their name attribute, which may not be duplicated within the same asset element.

As with the mesh element a transformation may be supplied either through the transform attribute or through a CSS3 transform.

        <assetmesh name="exampleMesh" style="transform: translate3d(0px, 0px, 10px)" type="triangles" material="#exampleMaterial">
          <data src="#myMeshData"></data>
          <assetdata src="#someMoreMeshData"></assetdata>
        </assetmesh>
      
attribute DOMString name
The name of this assetmesh element. The name is scoped to the surrounding asset element and may not be duplicated within this scope.
attribute DOMString includes
A space separated list of names corresponding to other assetmesh or assetdata elements that this one should extend.
attribute DOMString type
The primitive type of this assetmesh. Supported values are triangles, tristrips, points, lines, linestrips, and derived
attribute DOMString material
URI reference to a material element.
attribute DOMString transform
URI reference to a transform element.

Data and dataflow elements

The data element

Categories:
Data element

A data element is a non-leaf node in an Xflow graph. They act primarily as containers for data but may also modify that data through compute operators and filters. When data elements are nested the data from all child elements is merged, in this sense the parent data element acts as a data aggregator. In the case of two data fields with the same name the data element further down the list in the DOM will have priority. For example:

        <data> <!-- At this level "color" will be "0.0 1.0 0.0" -->
          <data>
            <float3 name="color">1.0 0.0 0.0</float3>
          </data>
          <data>
            <float3 name="color">0.0 1.0 0.0</float3>
          </data>
        </data>
        

Data elements may also reference other data elements. This can be used to share a common dataset between objects, overwriting certain fields on a per-object basis as required. See the data elements section for an example.

One important use for data elements is to dynamically change or generate data, for example to drive an animation or generate a ground mesh from a height map. This can be accomplished with a combination of compute operators and data overrides. The following is an example of a simple compute operator that will add the provided offset to all vertex positions of a mesh:

        <mesh>
           <data compute="position = xflow.add(position, offset)">
             <float3 name="offset">0.5 0.5 0.5 ... </float3>
             <data id="originalData">
                <float3 name="position">1.0 0.0 0.0 ... </float3>
             </data>
           </data>
        </mesh>
        
When using a compute operator with a data element all input arguments must be available to the data element that invokes the operator. In this example the "position" field of the mesh will contain the offset position data, while the data element with id originalData will contain the original positions. If this data element were referenced from another mesh it would also return the original positions:
        <mesh>
            <!-- "positions" contains the original data 1.0 0.0 0.0 ... -->
           <data src="#originalData"></data>
        </mesh>
        
Xflow is designed as a reactive framework, meaning operators will only be recomputed if input data has changed and a sink element has requested the output data (eg. during a draw call in a subsequent frame).
readonly attribute boolean complete
Returns true if all external resources required by this data have been loaded, false otherwise.
attribute DOMString compute
A Javascript-like statement that can invoke an Xflow compute operator on a set of input data. See the compute operator section for more information.
attribute DOMString filter
May contain a filter (keep, rename or remove) to adjust the data that is provided by this data element. See the Wiki page How to use Xflow for more information.
attribute DOMString src
Accepts an HTML ID reference to another data element. The other element's data will be included as an implicit first child of this data node. Note that in cases of duplicate data any child data or value elements will override the data found in the src node.
XML3DDataResult getResult(Array filter)
Returns a XML3DDataResult object containing the data for the fields requested by the given filter, eg. ["position", "index", "normal"]. This is useful for accessing the data directly through JavaScript.
Array getOutputNames()
Returns the names of the data fields provided by this data element.

The dataflow element

Categories:
Data element

The dataflow element can be thought of as a template for a compute operation consisting of one or more Xflow operators executed in sequence. This template can be defined once and then reused many times in the scene, applying the operations to a different set of input data each time. Consider the following dataflow example which computes skeletal animation for a mesh:

        <dataflow id="skinning" out="position, normal, boneXform">
          <float3 param="true" name="position" ></float3>
          <float3 param="true" name="normal" ></float3>
          <int4   param="true" name="boneIdx" ></int4>
          <float4 param="true" name="boneWeight" ></float4>

          <int    param="true" name="boneParent" ></int>
          <float3 param="true" name="bindTranslation" ></float3>
          <float4 param="true" name="bindRotation" ></float4>

          <float3 param="true" name="translation" ></float3>
          <float4 param="true" name="rotation" ></float4>

          <float  param="true" name="key" >0</float>
          <compute>
            bindPose = xflow.createTransformInv({translation: bindTranslation, rotation: bindRotation});
            bindPose = xflow.forwardKinematicsInv(boneParent, bindPose);

            rot = xflow.slerpSeq(rotation, key);
            trans = xflow.lerpSeq(translation, key);
            pose = xflow.createTransform({translation: trans, rotation: rot});
            pose = xflow.forwardKinematics(boneParent, pose);

            boneXform = xflow.mul(bindPose, pose);

            normal = xflow.skinDirection(normal, boneIdx, boneWeight, boneXform);
            position = xflow.skinPosition(position, boneIdx, boneWeight, boneXform);
          </compute>
        </dataflow>
        

By defining the param attribute of the various value elements we instruct Xflow to expect them as inputs provided by any element that references this dataflow. The compute element is only found inside dataflows and can be used to define a sequence of Xflow operators that should be applied to the input data. The list of operators will be computed from top to bottom and any new data fields they create (ie. bindPose in this example) can be used as input for operators further down the list.

To apply this dataflow to a set of data another data element may reference it in its own compute block or attribute:

        <data compute="position, normal = dataflow['#skinning']">
          <!-- We assume this file contains all the input data that the 'skinning' dataflow expects -->
          <data src="myMeshData.xml"></data>
          <float id="myAnimationKey" name="key">1.0<float>
        </data>
      

Conceptually this data element will 'call' the dataflow element with the input 'arguments' from the file myMeshData.xml and then assign the output of the dataflow to the position and normal fields, effectively overriding the ones found in myMeshData.xml. Note the URI fragment inside the dataflow[] construct. This may also reference an external document containing the dataflow.

By declaring the key value separately we can control the animation state of this model. Note also that the key is declared after the reference to myMeshData.xml to ensure that it overrides the key value found in the xml file.

attribute DOMString out
A comma-separated list of fields that this dataflow provides as output. If this attribute is not present then all computed fields will be provided as output.
readonly attribute boolean complete
Returns true if all external resources required by this dataflow have been loaded, false otherwise.
XML3DDataResult getResult(Array filter)
Returns a XML3DDataResult object containing the data for the fields requested by the given filter, eg. ["position", "index", "normal"]. This is useful for accessing the data directly through JavaScript.
Array getOutputNames()
Returns the names of the data fields provided by this data element.

The float, float2, float3, float4, and float4x4 elements

Categories:
Value element

The float* elements hold a space separated list of floating point values. The tag name determines how this data is interpreted, ie. a float2 element will interpret the data as an array of 2D vectors while a float4x4 element will interpret it as an array of 4x4 matrices.

attribute DOMString name
The name of the value element. A good name should be a semantic description of the data that this element holds.
attribute boolean param
Marks this value as one to be supplied by a different data element. Value elements with the param attribute are the only value elements that may be empty, all others must contain data. See the dataflow element for example usage.
attribute float key
A keyframe value to assist in defining animated values. A script may, for example, interpolate the data between successive keys.
void setScriptValue(Float32Array value)
A high performance setter to set the data of this value element directly through JavaScript.

The int and int4 elements

Categories:
Value element

The int* elements hold a space separated list of integer values. The tag name determines how this data is interpreted, ie. an int4 element will interpret the data as an array of 4-component integer vectors.

attribute DOMString name
The name of the value element. A good name should be a semantic description of the data that this element holds.
attribute boolean param
Marks this value as one to be supplied by a different data element. Value elements with the param attribute are the only value elements that may be empty, all others must contain data. See the dataflow element for example usage.
attribute float key
A keyframe value to assist in defining animated values. A script may, for example, interpolate the data between successive keys.
void setScriptValue(Int16Array value)
A high performance setter to set the data of this value element directly through JavaScript.

The bool element

Categories:
Value element

The bool element holds a space separated list of boolean values. The values may be given in string form (true/false) or as integers (1/0).

attribute DOMString name
The name of the value element. A good name should be a semantic description of the data that this element holds.
attribute boolean param
Marks this value as one to be supplied by a different data element. Value elements with the param attribute are the only value elements that may be empty, all others must contain data. See the dataflow element for example usage.
attribute float key
A keyframe value to assist in defining animated values. A script may, for example, interpolate the data between successive keys.
void setScriptValue(Int16Array value)
A high performance setter to set the data of this value element directly through JavaScript.

The string element

Categories:
Value element

The string element holds a comma separated list of string values.

Currently the following string attributes may be supplied by including a string element with the matching name:

Below is an example using a custom Xflow operator to change the type attribute of a mesh element:

          <!-- The custom xflow operator will output a string field named 'type' -->
          <data id="meshTypeCompute" compute="type = xflow.selectString(selector, value1, value2)">
              <string name="value1">triangles</string>
              <string name="value2">lines</string>
              <int name="selector">2</int>
          </data>

          <!-- In this case type will evaluate to 'lines' -->
          <mesh src="#meshdata" type="derived">
            <data src="#meshTypeCompute"></data>
          </mesh>
      
attribute DOMString name
The name of the value element. A good name should be a semantic description of the data that this element holds.
attribute boolean param
Marks this value as one to be supplied by a different data element. Value elements with the param attribute are the only value elements that may be empty, all others must contain data. See the dataflow element for example usage.
attribute float key
A keyframe value to assist in defining animated values. A script may, for example, interpolate the data between successive keys.
void setScriptValue(Array value)
A high performance setter to set the data of this value element directly through JavaScript.

The texture element

Categories:
Value element
Content model:
One or more img, video, or canvas elements
The texture element represents a texture that can be used as parameter for materials or as input for generic dataflow processing. The image data of the texture is defined by its children. The texture element's attributes determine how samples are derived from the image.

Texture sampling attributes configure fixed-function sampling methods on the graphics hardware. Thus these attributes qualify as CSS properties. We have abstained from using CSS properties because we currently cannot define custom CSS properties.

The wrap attribute controls the texture access if the provided texture coordinates are outside range [0;1]. The wrap attribute is a combined enumerated attribute. A valid wrap value is a string that matches the wrap production of the following form:
        wrap := <wrap-mode> <wrap-mode>?
        wrap-mode := repeat | clamp
      
If two wrap-mode values are given, then the first value defines the wrap mode for s coordinates and the second for t coordinates. Otherwise the wrap mode is applied in all directions. The wrap-mode values correspond to CLAMP_TO_EDGE and REPEAT in OpenGL.

The filter attribute controls the filtering of the texture, i.e. which texture pixel access function is used. The wrap attribute is a combined enumerated attribute. A valid filter value is a string that matches the filter production of the following form:
        filter := (<min-filter-mode> <mag-filter-mode>) | <mag-filter-mode>
        min-filter-mode := nearest | linear | nearest-mipmap-nearest | nearest-mipmap-linear | linear-mipmap-nearest | linear-mipmap-linear
        mag-filter-mode := nearest | linear
      
If only the mag-filter-mode is given, the specified function is used for both, minifying and magnification. Otherwise, the min-filter-mode is used for minifying and the mag-filter-mode is used for magnification. The functions specified by the filter modes correspond to those in OpenGL (NEAREST, LINEAR, NEAREST_MIPMAP_NEAREST, NEAREST_MIPMAP_LINEAR, LINEAR_MIPMAP_NEAREST, and LINEAR_MIPMAP_LINEAR). The default filter mode is "linear-mipmap-linear linear".

xml3d.js will automatically resize textures to the nearest power-of-two dimensions when the texture wrap mode is set to "repeat" or filtermin is set to anything other than "nearest" or "linear". See WebGL limitations for more information.

Here is an example of using the wrap and filter attributes to configure the sampling of a texture:
        <texture name="diffuseTexture" wrap="repeat clamp" filter="nearest linear">
          <img src="../stone.jpg"/>
        </texture>
      
The type attribute is an enumerated attribute with four states with three explicit keywords:
The 1D keyword, which maps to the 1D state
The 1D state means the children elements define a 1D texture each.
The 2D keyword, which maps to the 2D state
The 2D state means the children elements defines a 2D texture.
The 3D keyword, which maps to the 3D state
The 3D state means the children elements defines a 3D texture.
The auto state
The type of the texture is determined by the system based on the texture's children elements.

The type attribute's missing value default is the auto state.

attribute DOMString wrap
The wrap IDL attribute must reflect the respective content attribute of the same name.
attribute DOMString filter
The filter IDL attribute must reflect the respective content attribute of the same name.
attribute DOMString name
Required. The name of the texture as defined by the material shader.
attribute boolean param
If this element appears inside a DataFlow element the param attribute will mark it as a parameter to be supplied by the Data element referencing the DataFlow.
attribute DOMString type
The type IDL attribute must reflect the content attribute of the same name, limited to only known values.

Predefined models

Predefined primitive types

Triangle

Attribute name: triangles

WebGL primitive: TRIANGLE

Parameters:
Name Type Description
index int A list of indicies to build triangles out of.

The triangle primitive type renders faces out of sets of 3 vertices. Triangles may be constructed with or without an array of indices. If no indices are provided XML3D will construct the triangles from the array of vertex positions: the first 3 will create the first triangle, the next 3 the second and so on.

        <mesh type="triangles">
          <int name="index">0 1 2 1 3 2 ... </int>
          <float3 name="position">-1 -1 1  1 -1 1  -1 1 1  1 1 1 ... </float3>
        </mesh>
      

Tristrip

Attribute name: tristrips

WebGL primitive: TRIANGLE_STRIP

Parameters:
Name Type Description
index int A list of indicies to build tristrips out of.
vertexCount int The number of vertices or indices to use for each tristrip segment.

The tristrip primitive type creates triangles from a list of vertex positions and (optionally) a list of segments and/or indices. Each segment begins by building a triangle out of 3 vertex positions. Each subsequent triangle in the segment is then created from the last two vertex positions and the next one in the list. Note that this creates a sequence of connected triangles.

Segments can be used to create disconnected sets of triangles by providing a list of integers with the name vertexCount. Each number in the list specifies the number of vertex positions to use for that segment. XML3D will then work through the list of vertex positions sequentially building a tristrip for each segment.

        <mesh type="tristrips">
          <int name="vertexCount">4 4 4 4 4 4</int>
          <float3 name="position">-1 -1 1  1 -1 1  -1 1 1  1 1 1 ... </float3>
        </mesh>
      

Note that because the first triangle in a segment requires 3 vertex positions to define, a segment with vertex count 4 will create two triangles, while vertex count 5 will create 3 and so on.

Line

Attribute name: lines

WebGL primitive: LINES

Parameters:
Name Type Description
index int A list of indicies to build lines out of.

Lines are drawn from pairs of vertex positions and (optionally) a list of indices.

Linestrip

Attribute name: linestrips

WebGL primitive: LINE_STRIP

Parameters:
Name Type Description
index int A list of indicies to build linestrips out of.
vertexCount int The number of vertices or indices to use for each linestrip segment.

A linestrip is drawn from a list of vertex positions and (optionally) a list of segments and/or indices. For each segment a line is drawn between the first vertex and the second, then the second and the third and so on. This creates a continuous line.

      <mesh type="linestrips">
        <int name="vertexCount">4 2</int>
        <int name="index">0 1 2 3 1 3</int>
        <float3 name="position">-1 -1 1  1 -1 1  -1 1 1  1 1 1 ... </float3>
      </mesh>
      

The above example will create two line segments, the first using vertices 0, 1, 2, 3 and the second using vertices 1 and 3.

Point

Attribute name: points

WebGL primitive: POINT

The point primitive is drawn from a list of vertex positions, with each position being drawn as a single point. Points must use either the point material model or a custom material designed for point rendering.

Derived

Attribute name: derived

The special primitive type derived delegates the evaluation of the primitive type to the generic data model. The requested parameter has the name type. The contained value needs to match one of the primitive types above.

      <mesh type="derived">
        <string name="type">triangles</string>
        ...
      </mesh>
      

Predefined material models

Matte

URN: urn:xml3d:material:matte

Parameters:
Name Type Default Description
diffuseColor float3 1 1 1 The objects RGB color
useVertexColor bool false if true, the vertex attribute 'color' is used to color the object.

Simple material that does not apply any lighting but shades the object with a single uniform color defined by the diffuseColor parameter or by the vertex attribute color, if useVertexColor is set to ''true''.

Diffuse

URN: urn:xml3d:material:diffuse

Parameters:
Name Type Default Description
diffuseColor float3 1 1 1 The object's RGB diffuse color component.
diffuseTexture texture undefined Texture to read the diffuse color component and opacity (alpha) from. Accessed based on texcoord per-vertex attribute. If diffuseTexture is defined, the rgb channel of the diffuseTexture gets multiplied with the current diffuseColor and the the alpha channel gets multiples with the current opacity.
emissiveColor float3 0 0 0 The object's RGB emissive color component.
emissiveTexture texture undefined Texture to read the emissive color component from. Accessed based on texcoord per-vertex attribute. If emissiveTexture is defined, the emissiveColor gets multiplied with the color accessed from the texture.
ambientIntensity float 0 The amount of the 'diffuseColor' to be added to the shading without considering lighting.
opacity float 1 The opacity of the object, with 1 being opaque and 0 being fully transparent.
useVertexColor bool false Setting useVertexColor to 'true', the vertex attribute color will be multiplied to the diffuse color component (before the diffuseTexture gets applied).

The diffuse material model describes a diffuse surfaces that reflects light equally in all directions. Additionally, the surface has an optional emissive and ambient component. This is the logic of the diffuse material model in JavaScript/shade.js pseudo code:

        function shade(env) {
          var diffuseColor = env.diffuseColor || new Vec3(1, 1, 1);
          var emissiveColor = env.emissiveColor || new Vec3(0);
          var opacity = Math.max(1, env.opacity);

          if (env.useVertexColor && env.color) {
            diffuseColor *= new Vec3(env.color);
          }

          if (env.diffuseTexture && env.diffuseTexture.sample2D) {
             var texDiffuse = env.diffuseTexture.sample2D(env.texcoord);
             diffuseColor *= texDiffuse.rgb();
             opacity *= texDiffuse.a();
          }

          if (env.emissiveTexture && env.emissiveTexture.sample2D) {
             var texEmissive = env.emissiveTexture.sample2D(env.texcoord);
             emissiveColor *= texEmissive.rgb();
          }

          return Shade.diffuse(diffuseColor, env.normal)
                      .transparent(1.0 - opacity)
                      .emissive(emissiveColor);
        }
      

Phong

URN: urn:xml3d:material:phong

Parameters:
Name Type Default Description
diffuseColor float3 1 1 1 The object's RGB diffuse color component.
diffuseTexture texture undefined Texture to read the diffuse color component and opacity (alpha) from. Accessed based on texcoord per-vertex attribute. If diffuseTexture is defined, the rgb channel of the diffuseTexture gets multiplied with the current diffuseColor and the the alpha channel gets multiples with the current opacity.
specularColor float3 0 0 0 The object's RGB specular color component.
specularTexture texture undefined Texture to read the specular color component from. Accessed based on texcoord per-vertex attribute. If specularTexture is defined, the specularColor gets multiplied with the rgb-color accessed from the texture.
shininess float 0.5 A scalar for the object's specular exponent, to be multiplied by 128 (e.g. a value of 0.5 will give a specular exponent of 64)
emissiveColor float3 0 0 0 The object's RGB emissive color component.
emissiveTexture texture undefined Texture to read the emissive color component from. Accessed based on texcoord per-vertex attribute. If emissiveTexture is defined, the emissiveColor gets multiplied with the rgb-color accessed from the texture.
ambientIntensity float 0 The amount of the 'diffuseColor' to be added to the shading without considering lighting.
opacity float 1 The opacity of the object, with 1 being opaque and 0 being fully transparent.
useVertexColor bool false Setting useVertexColor to 'true', the vertex attribute 'color' will be multiplied to the diffuse color component.

The phong material model extends the diffuse material model by the specular term from the Phong reflection model. The additional parameters are specularColor, specularTexture and shininess. This is the logic of the phong material model in JavaScript/shade.js pseudo code:

        function shade(env) {
          var diffuseColor = env.diffuseColor || new Vec3(1, 1, 1);
          var specularColor = env.specularColor || new Vec3(0, 0, 0);
          var emissiveColor = env.emissiveColor || new Vec3(0);
          var opacity = Math.max(1, env.opacity);
          var shininess = env.shininess != undefined ? env.shininess : 0.5;

          if (env.useVertexColor && env.color) {
            diffuseColor *= new Vec3(env.color);
          }

          if (env.diffuseTexture && env.diffuseTexture.sample2D) {
             var texDiffuse = env.diffuseTexture.sample2D(env.texcoord);
             diffuseColor *= texDiffuse.rgb();
             opacity *= texDiffuse.a();
          }

          if (env.specularTexture && env.specularTexture.sample2D) {
             var texSpecular = env.specularTexture.sample2D(env.texcoord);
             diffuseColor *= texSpecular.rgb();
          }

          if (env.emissiveTexture && env.emissiveTexture.sample2D) {
             var texEmissive = env.emissiveTexture.sample2D(env.texcoord);
             emissiveColor *= texEmissive.rgb();
          }


          return Shade.diffuse(diffuseColor, env.normal)
                      .phong(specularColor, env.normal, shininess)
                      .transparent(1.0 - opacity)
                      .emissive(emissiveColor);
        }
      

Point

URN: urn:xml3d:material:point

Parameters:
Name Type Default Description
diffuseColor float3 1 1 1 The objects RGB color
useVertexColor bool false if true, the vertex attribute 'color' is used to color the object.
texCoordOffset float2 0 0 An offset to add to the texture coordinates for each point.
texCoordSize float2 1 1 A scale factor to multiply the texture coordinates of each point with. Only applies to the implicit texture coordinate defined by gl_PointCoord, not the optional texcoord vertex attribute. See the note below for more information.
pointSize float 1 The base size of each point. Will be scaled by distance from the camera.

For points, texture coordinates are a mixture of the texcoord attribute and the gl_PointCoord value provided by WebGL. The final texture coordinate for each fragment is calculated as follows:

  vec2 uv = texcoord + texCoordOffset + (gl_PointCoord * texCoordSize);

The point material model is always used in conjunction with the point primitive type.

Predefined light models

Point Lights

URN: urn:xml3d:light:point

Parameters:
Name Type Default Description
position float3 0 0 0 The position of the point light in object space
attenuation float3 0 0 1 The attenuation of the point light given as its constant, linear, e.g quadratic component.
intensity float3 1 1 1 The RGB intensity of the point light.

Point light sources emit light from a single point in space with a uniform distribution in all directions, i.e. omnidirectional. The position of the point light is defined by its position attribute and affected by the transformation of the light element that defines the occurrence of the point light. The orientation of the light element is not influencing the light.

Directional Lights

URN: urn:xml3d:light:directional

Parameters:
Name Type Default Description
direction float3 0 0 -1 The direction of the light in object space.
intensity float3 1 1 1 The RGB intensity of the point light.

Directional light sources, also known as distant light sources, emit light along parallel rays from an infinite distance away. The direction the light sources emits from is defined by its direction attribute and affected by the transformation of the light element that defines the occurrence of the distant light. The position of the light element is not taken into account.

Spot Lights

URN: urn:xml3d:light:spot

Parameters:
Name Type Default Description
position float3 0 0 0 The position of the point light in object space
direction float3 0 0 -1 The direction of the light in object space.
intensity float3 1 1 1 The RGB intensity of the directional light.
attenuation float3 0 0 1 The attenuation of the point light given as its constant, linear, e.g quadratic component.
cutoffAngle float Math.PI/4 Spot angle in radians. Controls the size of the outer cone of a spot light, i.e. the circular area a spot light covers.
softness float 0 Softness of the spot light in the range [0;1].

Spot light source are a variation of point lights: Instead of emitting light omnidirectional, they emit light from their position in a cone of direction. The cutoffAngle attribute defines the size of the cone. Objects outside the cone defined by the cutoffAngle are not lit by the light source. The softness attribute defines the percentage of the cone in which the illumination ramps down from full to no illumination, i.e. a softness of 0 specifies a hard transition between full to no illumination and a softness of 1.0 a linear transition along the radius of the cone.

Predefined view models

This section describes the currently available predefined view models.

Perspective

URN: urn:xml3d:view:perspective

Parameters:
Name Type Default Description
fovVertical float Math.PI / 4 The vertical field of view of the view frustum in radians
fovHorizontal float - The horizontal field of view of the view frustum in radians
near float - The distance of the near clipping plane (unitless)
far float - The distance of the far clipping plane (unitless)

The perspective view model defines a perspective view frustum based on the near and far planes and on a vertical or horizontal opening angle. A small field of view roughly corresponds to a telephoto lens; a large field of view roughly corresponds to a wide-angle lens. If fovHorizontal is given, the frustum is defined using this horizontal angle, otherwise fovVertical is used. If the far or the near clipping place is not defined, the system will try to compute a useful value automatically based on the scene's dimension.

Projective

URN: urn:xml3d:view:projective

Parameters:
Name Type Default Description
projectionMatrix float4x4 The frustum described as projection matrix

The projective view model defines a projective view frustum based on a projection matrix. This view model is typically used, if the intrisic camera parameters are computed, e.g. from a webcam image using computer vision algorithms.

Materials

Materials are responsible for describing how an object should be rendered. In XML3D materials generally have two parts: a set of textures and parameters and some code that uses these components to determine the final color of each point on the surface of an object. On the web this will usually consist of WebGL shader code (GLSL) or Shade.js code.

In XML3D this combination of parameters and code is called the material model. A material element represents an instance of a particular material model, allowing the parameters to be changed. XML3D contains several predefined material models. It also offers an interface and set of conventions for defining custom material models.

Custom materials

XML3D provides an interface to define custom materials in addition to the predefined material models. Such materials must first be registered with XML3D:

        XML3D.materials.register("my-material", { ...material definition... });
    

and may then be referenced through the model attribute of a material element:

        <material model="urn:xml3d:materials:my-material"></material>
    

The material definition must provide vertex and fragment shader code in the form of a string as well as definitions and default values for all uniform and sampler variables:

        XML3D.materials.register("my-material", {
            vertex : "...vertex shader code...",
            fragment : "...fragment shader code...",

            //All uniform variables that appear in either shader block, with default values
            uniforms : {
                exampleFloat : 0.5,
                exampleVec3  : [1, 1, 1]
            },

            //All textures that appear in either shader block
            samplers : {
                exampleTexture : null
            },

            //All vertex attributes that appear in the vertex shader
            attributes : {
                position : {required : true},
                normal : null //Synonymous with {required : false}
                exampleVertexAttribute : {required : false},
            },

            //Optional function to mark this material as requiring alpha blending
            hasTransparency : function(params) {
                return params.opacity && params.opacity.getValue()[0] < 1;
            },

            //Optional function to add compiler directives to shaders based on scene parameters (eg. the number of lights)
            addDirectives : function(directives, lights, params) {
                directives.push("HAS_EXAMPLETEXTURE " + ('exampleTexture' in params ? "1" : "0"));
            }
        });
    

As with the predefined material models the generic data model can be used to set material parameters like uniform variables and textures for custom materials:

        <material model="urn:xml3d:material:my-material">
            <float3 name="exampleVec3">0 1 0</float3>
            <texture name="exampleTexture">
                <img src="textures/my-example-texture.png"/>
            </texture>
        </material>
    

Custom materials may also be defined through shade.js which is generally easier to use and is able to generate cross platform materials that may be used outside of XML3D as well.

Be careful with materials that modify the vertex positions of a mesh. These objects will not be pickable and may have incorrect bounding boxes, which can lead to incorrect clipping planes and frustum culling in the camera. If your material falls into this category you should always provide a reasonable bounding box for the object manually:
    <mesh src="myMesh.xml" material="#my-material">
        <float3 name="boundingBox">-10 -10 -10 5 5 5</float3> <!-- min max points of the bounding box -->
    </mesh>
    

Web Components

XML3D supports the web component approach to defining custom HTML objects that can be easily encapsulated and shared.

Web Components are a new technology still under development by the major browsers. In some browsers they may need to be explicitly enabled, others may not support them at all. In these cases a web components polyfill will need to be included in the page.

The following example shows a simple web component that instantiates a cube:

        <!-- Component registration -->
        <script type="text/javascript">
            window.addEventListener("load", function() {
                // This function takes care of registering the web component with the browser
                XML3D.registerComponent(document.querySelector("#cube-template"));
            });
        </script>

        <!-- Component template -->
        <template id="cube-template" name="x-cube">
            <material id="cube-material" model="urn:xml3d:material:phong">
                <float3 name="diffuseColor">0 1 0</float3>
            </material>          
            <mesh material="#cube-material" src="myCubeMesh.xml" type="triangles"></mesh>
        </template>

        <!-- Instantiating a component -->
        <xml3d>
            <group style="transform: translate3d(0,0,-10px)">
                <x-cube></x-cube>
            </group>
        </xml3d>
    

The following rules and limitations also apply to components:

Registration

Web components must be registered with the browser before they can be used. XML3D provides a convenience interface for this and it is recommended that you use this to register your web components rather than registering them manually. The simplest way to register a web component is to pass a URL string to an HTML file containing the template element:

            var promise = XML3D.registerComponent("path/to/component/template.html");
        

The registration function will return a Promise object that resolves when the component template has been registered with the browser. At that point you may begin creating instances of the component. The Promise will reject if the component template could not be found or if an error was encountered during the registration process.

Optionally you can include your own prototype object for a web component. This allows you to hook into the standard lifecycle callbacks of the web component (eg. createdCallback) and to define custom functions that will be available on your web component. The example below registers a component that provides the function myFunction on the web component's DOM element:

            var myPrototype = {
               myFunction : function() { ... },
               createdCallback : function() { ... }
            };

            XML3D.registerComponent("path/to/component/template.html", {proto: myPrototype});

            document.body.appendChild(document.createElement("my-component")); // createdCallback would be called here
            document.querySelector("my-component").myFunction();
        

For more information about the various lifecycle callbacks see the Custom Elements documentation. Note that XML3D's own lifecycle callbacks will always be called first even when providing your own. These internal callbacks will take care of things like creating a shadow root and filling it with the component's template.

Configuration

XML3D supports using content elements and attributes to configure web components. The following example uses a content element to configure the color of the cube and an attribute to configure its opacity:

            <template opacity="1" name="x-cube">
                <material id="cube-material" model="urn:xml3d:material:phong">
                    <content select="float3[name='diffuseColor']"> <!-- Select a float3 element with the name 'diffuseColor' -->
                        <float3 name="diffuseColor">0 1 0</float3>
                    </content>
                    <float name="opacity">{{opacity}}</float> <!-- Take opacity from the 'opacity' attribute -->
                </material>
                <mesh material="#cube-material" src="myCubeMesh.xml" type="triangles"></mesh>
            </template>

            <xml3d>
                <group style="transform: translate3d(0,0,-10px)">
                    <x-cube opacity="0.5"> <!-- Set the cube's opacity to 0.5 -->
                        <float3 name="diffuseColor">1 0 1</float3> <!-- This float3 will be appended to the above content slot, overriding the default float3 -->
                    </x-cube>
                </group>
            </xml3d>
        

Content elements can also be used to add renderable objects or even other web components, however in this case they will not override existing defaults, but will instead be rendered alongside them:

            <template id="cube-template" name="x-cube">
                <material id="cube-material" model="urn:xml3d:material:phong">
                    <content select="float3[name='diffuseColor']">
                        <float3 name="diffuseColor">0 1 0</float3>
                    </content>
                </material>
                <content select="mesh">
                    <mesh material="#cube-material" src="myCubeMesh.xml" type="triangles"></mesh>
                    <!-- The below mesh will be inserted here -->
                </content>
                <content select=".otherComponent">
                    <!-- The below x-cube instance with the class 'otherComponent' will be inserted here -->
                </content>
            </template>

            <xml3d>
                <group style="transform: translate3d(0,0,-10px)">
                    <x-cube>
                        <float3 name="diffuseColor">1 0 1</float3>
                        <mesh src="myCubeMesh.xml" type="triangles"></mesh> <!-- This x-cube component now contains 2 overlapping cubes -->
                        <x-cube class="otherComponent"></x-cube>            <!-- This x-cube component now contains 3 overlapping cubes -->
                    </x-cube>
                </group>
            </xml3d>
        

Global options

XML3D provides a set of global options through the XML3D.options interface. These options are shared between all XML3D elements on a page.

string getValue(string key)
Returns the current value of the option with the matching key.
void setValue(string key, string value)
Set the option with the given key to the given value.
Array getKeys()
Returns an array of all available option keys.
void addObserver(string key, function observer)
Adds a change observer to the option with the given key. Supports the '*' wildcard to observe all options.
void removeObserver(function observer)
Removes the given change observer from all keys.
void resetValue(string key)
Resets the value of the option with the matching key to the default value.
void setOptionsFromQuery()
Parses the page URL for option keys and values in the standard query form. Done once automatically on page load.

Currently the following options are available in xml3d.js, the default is shown in bold:

Key Values Description
loglevel all, debug, info, warning, error, exception Controls the level of logging to the console.
resource-crossorigin-attribute anonymous, use-credentials This value will be assigned to the crossOrigin field of requested resources such as img or video.
renderer-faceculling back, front, both, none Controls which faces are culled during rendering. Corresponds to WebGL's cullFace function.
renderer-frontface cw, ccw Controls the winding order of polygon faces during rendering. Corresponds to WebGL's frontFace function.
renderer-frustum-culling true, false Toggles view frustum culling during rendering.
renderer-mousemove-picking true, false Enable object picking for mousemove events. Ex: The XML3D standard camera disables mousemove picking between the mousedown and mouseup events of a camera rotation.
renderer-movement-aware-click-handler true, false When true, disregard click events where the mouse has moved between the mousedown and mouseup events.
renderer-continuous true, false Toggle continuous rendering. If false a frame will only be drawn if XML3D detects a scene change that requires it.
renderer-ssao true, false Toggle screen space ambient occlusion. Note: This is an experimental feature! You will probably need to tweak the SSAO parameters to fit your scene. See XML3D.options.getKeys() for additional parameters.
renderer-sort-opaque-objects true, false When true opaque objects are sorted each frame to be rendered front to back.
These options can also be set through URL queries by appending xml3d-, like so: ?xml3d-loglevel=debug

Content-Types

XML3D specifies the following content-types for external resources:

        JSON mesh file     model/vnd.xml3d.mesh+json

        XML mesh file      model/vnd.xml3d.mesh+xml

        XML asset file     model/vnd.xml3d.model+xml
    

The response should include a Content-Type header with the same content-type or the appropriate standard type application/json, application/xml or application/octet-stream.

A response with no Content-Type header at all will not be handled and will generate an error message.

Datatypes

XML3D provides a range of math types based on the glMatrix library. In general the functions they provide are immutable, with the exception of the Box and Ray types.

Vec2

A two component vector object.

attribute Float32Array data
The underlying typed array that this Vec2 wraps.
attribute float x
Provides mutable access to the first component of this vector.
attribute float y
Provides mutable access to the second component of this vector.
static Vec2 fromDOMString(DOMString str)
Creates a new Vec2 object from the space-separated string representation as used in XML3D element attributes.
DOMString toDOMString()
Returns a space-seperated string representation for use in XML3D element attributes or value elements.
Constructor ()
Creates a new identity Vec2 [0,0]
Constructor (float x, float y)
Creates a new Vec2 from the given values.
Constructor (Float32Array other)
Creates a new Vec2 which is a copy of the values in the passed array.
Constructor (Vec2 other)
Creates a new Vec2 which is a copy of the given Vec2.
Vec2 add(Vec2 other)
Returns the component wise addition of the two vectors as a new Vec2.
Vec2 clone()
Returns a new copy of this Vec2.
float dist(Vec2 other)
The distance between this and the given vector.
Vec2 divide(Vec2 other)
Returns the component wise division of the two vectors as a new Vec2.
float dot(Vec2 other)
The dot product of this and the given vector.
float length()
Returns the length of this vector.
Vec2 lerp()
Returns a linear interpolation between the two vectors as a new Vec2.
Vec2 other
float weight
Interpolation amount between the two vectors, range of [0,1].
Vec2 max(Vec2 other)
Returns a new Vec2 that contains the component wise maximum of the two vectors.
Vec2 min(Vec2 other)
Returns a new Vec2 that contains the component wise minimum of the two vectors.
Vec2 mul(Vec2 other)
Returns the component wise multiplication of the two vectors as a new Vec2.
Vec2 mul(Mat2 other)
Returns the transformation of this vector with the given 2x2 matrix as a new Vec2.
Vec2 mul(Mat3 other)
Returns the transformation of this vector with the given 3x3 matrix as a new Vec2. The third vector component is implicitly '1'.
Vec2 mul(Mat4 other)
Returns the transformation of this vector with the given 4x4 matrix as a new Vec2. The third vector component is implicitly '0', the fourth '1'.
Vec2 negate()
Returns the component wise negation of this vector as a new Vec2.
Vec2 normalize()
Returns the normalized representation of this vector as a new Vec2.
static Vec2 random(optional float scale)
Generates a random vector with the given scale, or a unit vector if omitted.
Vec2 scale(float scale)
Returns the scaled vector as a new Vec2.
Vec2 sub(Vec2 other)
Returns the component wise subtraction of the two vectors as a new Vec2.
static Vec2 wrap(Float32Array data)
Returns a new Vec2 wrapper around the given Float32Array. Note: Changes to the returned Vec2 will also change the data in the array!

Vec3

A three component vector object.

attribute Float32Array data
The underlying typed array that this Vec3 wraps.
attribute float x
Provides mutable access to the first component of this vector.
attribute float y
Provides mutable access to the second component of this vector.
attribute float z
Provides mutable access to the third component of this vector.
static Vec3 fromDOMString(DOMString str)
Creates a new Vec3 object from the space-separated string representation as used in XML3D element attributes.
DOMString toDOMString()
Returns a space-seperated string representation for use in XML3D element attributes or value elements.
Constructor ()
Creates a new identity Vec3 [0,0,0]
Constructor (float x, float y, float z)
Creates a new Vec3 from the given values.
Constructor (Float32Array other)
Creates a new Vec3 which is a copy of the values in the passed array.
Constructor (Vec3 other)
Creates a new Vec3 which is a copy of the given Vec3.
Vec3 add(Vec3 other)
Returns the component wise addition of the two vectors as a new Vec3.
Vec3 clone()
Returns a new copy of this Vec3.
Vec3 cross(Vec3 other)
Returns the cross product of this and the other vector as a new Vec3.
float dist(Vec3 other)
The distance between this and the given vector.
Vec3 divide(Vec3 other)
Returns the component wise division of the two vectors as a new Vec3.
float dot(Vec3 other)
The dot product of this and the given vector.
float length()
Returns the length of this vector.
Vec3 lerp()
Returns a linear interpolation between the two vectors as a new Vec3.
Vec3 other
float weight
Interpolation amount between the two vectors, range of [0,1].
Vec3 max(Vec3 other)
Returns a new Vec3 that contains the component wise maximum of the two vectors.
Vec3 min(Vec3 other)
Returns a new Vec3 that contains the component wise minimum of the two vectors.
Vec3 mul(Vec3 other)
Returns the component wise multiplication of the two vectors as a new Vec3.
Vec3 mul(Mat3 other)
Returns the transformation of this vector with the given 3x3 matrix as a new Vec3.
Vec3 mul(Mat4 other)
Returns the transformation of this vector with the given 4x4 matrix as a new Vec3. The fourth vector component is implicitly '1'
Vec3 mul(Quat q)
Returns the transformation of this vector with the given quaternion as a new Vec3.
Vec3 negate()
Returns the component wise negation of this vector as a new Vec3.
Vec3 normalize()
Returns the normalized representation of this vector as a new Vec3.
static Vec3 random(optional float scale)
Generates a random vector with the given scale, or a unit vector if omitted.
Vec3 reciprocal()
Returns the component wise reciprocal of this vector as a new Vec3.
Vec3 scale(float scale)
Returns the scaled vector as a new Vec3.
Vec3 sub(Vec3 other)
Returns the component wise subtraction of the two vectors as a new Vec3.
Vec3 transformDirection(Mat4 mat)
Returns the transformation of this vector with the given 4x4 matrix as a new Vec3. The fourth vector component is implicitly '0'
static Vec3 wrap(Float32Array data)
Returns a new Vec3 wrapper around the given Float32Array. Note: Changes to the returned Vec3 will also change the data in the array!

Vec4

A four component vector object.

attribute Float32Array data
The underlying typed array that this Vec4 wraps.
attribute float x
Provides mutable access to the first component of this vector.
attribute float y
Provides mutable access to the second component of this vector.
attribute float z
Provides mutable access to the third component of this vector.
attribute float w
Provides mutable access to the fourth component of this vector.
static Vec4 fromDOMString(DOMString str)
Creates a new Vec4 object from the space-separated string representation as used in XML3D element attributes.
DOMString toDOMString()
Returns a space-seperated string representation for use in XML3D element attributes or value elements.
Constructor ()
Creates a new identity Vec4 [0,0,0,0]
Constructor (float x, float y, float z, float w)
Creates a new Vec4 from the given values.
Constructor (Float32Array other)
Creates a new Vec4 which is a copy of the values in the passed array.
Constructor (Vec4 other)
Creates a new Vec4 which is a copy of the given Vec4.
Vec4 add(Vec4 other)
Returns the component wise addition of the two vectors as a new Vec4.
Vec4 clone()
Returns a new copy of this Vec4.
float dist(Vec4 other)
The distance between this and the given vector.
Vec4 divide(Vec4 other)
Returns the component wise division of the two vectors as a new Vec4.
float dot(Vec4 other)
The dot product of this and the given vector.
float length()
Returns the length of this vector.
Vec4 lerp()
Returns a linear interpolation between the two vectors as a new Vec4.
Vec4 other
float weight
Interpolation amount between the two vectors, range of [0,1].
Vec4 max(Vec4 other)
Returns a new Vec4 that contains the component wise maximum of the two vectors.
Vec4 min(Vec4 other)
Returns a new Vec4 that contains the component wise minimum of the two vectors.
Vec4 mul(Vec4 other)
Returns the component wise multiplication of the two vectors as a new Vec4.
Vec4 mul(Mat4 other)
Returns the transformation of this vector with the given 4x4 matrix as a new Vec4.
Vec4 negate()
Returns the component wise negation of this vector as a new Vec4.
Vec4 normalize()
Returns the normalized representation of this vector as a new Vec4.
static Vec4 random(optional float scale)
Generates a random vector with the given scale, or a unit vector if omitted.
Vec4 scale(float scale)
Returns the scaled vector as a new Vec4.
Vec4 sub(Vec4 other)
Returns the component wise subtraction of the two vectors as a new Vec4.
Vec4 transformQuat(Quat q)
Returns the transformation of this vector with the given quaternion as a new Vec4.
static Vec4 wrap(Float32Array data)
Returns a new Vec4 wrapper around the given Float32Array. Note: Changes to the returned Vec4 will also change the data in the array!

AxisAngle

An axis-angle representation of a rotation with the angle in radians. This type is used for all XML3D interface methods and element attributes that expect a rotation. When working with rotations mathematically it's best to first convert the AxisAngle representation to a Quat and convert back to AxisAngle when passing the result back to an XML3D interface.

attribute Float32Array data
The underlying typed array that this AxisAngle wraps in the form [x, y, z, angle]
attribute Vec3 axis
Provides mutable access to the axis vector.
attribute float angle
Provides mutable access to the angle component. The angle should always be in radians.
static AxisAngle fromDOMString(DOMString str)
Creates a new AxisAngle object from the space-separated string representation as used in XML3D element attributes.
DOMString toDOMString()
Returns a space-seperated string representation for use in XML3D element attributes or value elements.
Constructor ()
Creates a new identity AxisAngle [0,0,1,0]
Constructor (float x, float y, float z, float angle)
Creates a new AxisAngle from the given values.
Constructor (Float32Array other)
Creates a new AxisAngle which is a copy of the values in the passed array.
Constructor (AxisAngle other)
Creates a new AxisAngle which is a copy of the given AxisAngle.
AxisAngle clone()
Returns a new copy of this AxisAngle.
static AxisAngle fromQuat(Quat q)
Creates a new axis-angle representation of the given quaternion's rotation.
Quat toQuat()
Creates a new quaternion representation of this AxisAngle's rotation.
static AxisAngle wrap(Float32Array data)
Returns a new AxisAngle wrapper around the given Float32Array. Note: Changes to the returned AxisAngle will also change the data in the array!

Quat

Quat represents a rotation as a quaternion of the form [x, y, z, w]. The provided functions and accessors do not automatically normalize the quaternion unless otherwise stated.

attribute Float32Array data
The underlying typed array that this Quat wraps.
attribute float x
Provides mutable access to the first component of this quaternion.
attribute float y
Provides mutable access to the second component of this quaternion.
attribute float z
Provides mutable access to the third component of this quaternion.
attribute float w
Provides mutable access to the fourth component of this quaternion.
static Quat fromDOMString(DOMString str)
Creates a new Quat object from a space-separated string representation.
DOMString toDOMString()
Returns a space-seperated string representation for use in XML3D element attributes or value elements.
Constructor ()
Creates a new identity Quat [0,0,0,1]
Constructor (float x, float y, float z, float w)
Creates a new Quat from the given values.
Constructor (Float32Array other)
Creates a new Quat which is a copy of the values in the passed array.
Constructor (Quat other)
Creates a new Quat which is a copy of the given Quat.
Quat add(Quat other)
Returns the addition of the two quaternions as a new Quat.
Quat clone()
Returns a new copy of this Quat.
Quat calculateW()
Returns a new Quat with the w component calculated from the x,y,z components of this quaternion. Any existing w component will be ignored.
Quat conjugate()
Returns the conjugate of this quaternion as a new Quat. Note: This method should only be used on normalized quaternions!
float dot(Quat other)
Returns the dot product of the two quaternions.
Quat invert()
Returns the inverse of this quaternion as a new Quat. This is slower than Quat.conjugate but also works on non-normalized quaternions.
float length()
Returns the magnitude of this quaternion.
Quat lerp()
Returns a linear interpolation between the two quaternions as a new Quat.
Quat other
float weight
Interpolation amount between the two quaternions, range of [0,1].
Quat mul(Quat other)
Returns the component wise multiplication of the two quaternions as a new Quat.
Quat normalize()
Returns the normalized representation of this quaternion as a new Quat.
Quat rotateX(float angleInRadians)
Returns a new quaternion representing this one rotated around the X axis by the given angle.
Quat rotateY(float angleInRadians)
Returns a new quaternion representing this one rotated around the Y axis by the given angle.
Quat rotateZ(float angleInRadians)
Returns a new quaternion representing this one rotated around the Z axis by the given angle.
Quat scale(float scale)
Returns the scaled quaternion as a new Quat. This is identical to Vec4.scale.
static Quat fromAxisAngle(AxisAngle a)
Generates a normalized quaternion representation of the given AxisAngle.
static Quat fromBasis(Vec3 x, Vec3 y, Vec3 z)
Generates a normalized quaternion from the given basis vectors, defined as the rotation between the coordinate space defined by these vectors and the standard space.
static Quat fromMat3(Mat3 mat)
Generates a normalized quaternion from the given rotation matrix.
static Quat fromRotationTo(Vec3 from, Vec3 to)
Generates a normalized quaternion representing the shortest rotation from one vector to another.
Quat slerp()
Returns a spherical linear interpolation between the two quaternions as a new Quat.
Quat other
float weight
Interpolation amount between the two quaternions, range of [0,1].
static Quat wrap(Float32Array data)
Returns a new Quat wrapper around the given Float32Array. Note: Changes to the returned Quat will also change the data in the array!

Mat2

A 2x2 matrix object.

attribute Float32Array data
The underlying typed array that this Mat2 wraps.
attribute float m11
Provides mutable access to the first column of the first row of this matrix.
attribute float m12
Provides mutable access to the second column of the first row of this matrix.
attribute float m21
Provides mutable access to the first column of the second row of this matrix.
attribute float m22
Provides mutable access to the second column of the second row of this matrix.
Constructor ()
Creates a new identity Mat2.
Constructor (Float32Array other)
Creates a new Mat2 which is a copy of the values in the passed array.
Constructor (Mat2 other)
Creates a new Mat2 which is a copy of the given Mat2.
Mat2 adjoint()
Computes the adjugate of this matrix as a new Mat2.
Mat2 clone()
Returns a new copy of this Mat2.
float determinant()
Computes the determinant of this matrix.
Mat2 invert()
Returns the inverse of this matrix as a new Mat2. If this matrix is not invertible null will be returned.
Mat2 mul(Mat2 other)
Returns the multiplication of this matrix with the other as a new Mat2.
Mat2 rotate(float angleInRadians)
Returns the rotation of this matrix by the given angle in radians as a new Mat2.
Mat2 scale(Vec2 scale)
Returns the scaled matrix as a new Mat2.
Mat2 transpose()
Returns the transpose of this matrix as a new Mat2.
static Mat2 wrap(Float32Array data)
Returns a new Mat2 wrapper around the given Float32Array. Note: Changes to the returned Mat2 will also change the data in the array!

Mat3

A 3x3 matrix object.

attribute Float32Array data
The underlying typed array that this Mat3 wraps.
attribute float m11
Provides mutable access to the first column of the first row of this matrix.
attribute float m12
Provides mutable access to the second column of the first row of this matrix.
attribute float m13
Provides mutable access to the third column of the first row of this matrix.
attribute float m21
Provides mutable access to the first column of the second row of this matrix.
attribute float m22
Provides mutable access to the second column of the second row of this matrix.
attribute float m23
Provides mutable access to the third column of the second row of this matrix.
attribute float m31
Provides mutable access to the first column of the third row of this matrix.
attribute float m32
Provides mutable access to the second column of the third row of this matrix.
attribute float m33
Provides mutable access to the third column of the third row of this matrix.
Constructor ()
Creates a new identity Mat3.
Constructor (Float32Array other)
Creates a new Mat3 which is a copy of the values in the passed array.
Constructor (Mat3 other)
Creates a new Mat3 which is a copy of the given Mat3.
Mat3 adjoint()
Computes the adjugate of this matrix as a new Mat3.
Mat3 clone()
Returns a new copy of this Mat3.
float determinant()
Computes the determinant of this matrix.
static Mat3 fromMat4(Mat4 mat)
Creates a new Mat3 from the upper-left values of the given 4x4 matrix.
static Mat3 fromQuat(Quat q)
Creates a new 3x3 rotation matrix from the given quaternion.
static Mat3 normalFromMat4(Mat4 mat)
Creates a 3x3 normal matrix (transpose inverse) from the given 4x4 matrix.
Mat3 invert()
Returns the inverse of this matrix as a new Mat3. If this matrix is not invertible null will be returned.
Mat3 mul(Mat3 other)
Returns the multiplication of this matrix with the other as a new Mat3.
Mat3 rotate(float angleInRadians)
Returns the rotation of this matrix by the given angle in radians as a new Mat3.
Mat3 scale(Vec3 scale)
Returns the scaled matrix as a new Mat3.
Mat3 translate(Vec3 translation)
Returns the translated matrix as a new Mat3.
Mat3 transpose()
Returns the transpose of this matrix as a new Mat3.
static Mat3 wrap(Float32Array data)
Returns a new Mat3 wrapper around the given Float32Array. Note: Changes to the returned Mat3 will also change the data in the array!

Mat4

A 4x4 matrix object.

attribute Float32Array data
The underlying typed array that this Mat4 wraps.
attribute float m11
Provides mutable access to the first column of the first row of this matrix.
attribute float m12
Provides mutable access to the second column of the first row of this matrix.
attribute float m13
Provides mutable access to the third column of the first row of this matrix.
attribute float m14
Provides mutable access to the fourth column of the first row of this matrix.
attribute float m21
Provides mutable access to the first column of the second row of this matrix.
attribute float m22
Provides mutable access to the second column of the second row of this matrix.
attribute float m23
Provides mutable access to the third column of the second row of this matrix.
attribute float m24
Provides mutable access to the fourth column of the second row of this matrix.
attribute float m31
Provides mutable access to the first column of the third row of this matrix.
attribute float m32
Provides mutable access to the second column of the third row of this matrix.
attribute float m33
Provides mutable access to the third column of the third row of this matrix.
attribute float m34
Provides mutable access to the fourth column of the third row of this matrix.
attribute float m41
Provides mutable access to the first column of the fourth row of this matrix.
attribute float m42
Provides mutable access to the second column of the fourth row of this matrix.
attribute float m43
Provides mutable access to the third column of the fourth row of this matrix.
attribute float m44
Provides mutable access to the fourth column of the fourth row of this matrix.
Constructor ()
Creates a new identity Mat4.
Constructor (Float32Array other)
Creates a new Mat4 which is a copy of the values in the passed array.
Constructor (Mat4 other)
Creates a new Mat4 which is a copy of the given Mat4.
Mat4 adjoint()
Computes the adjugate of this matrix as a new Mat4.
Mat4 clone()
Returns a new copy of this Mat4.
float determinant()
Computes the determinant of this matrix.
static Mat4 frustum(float left, float right, float bottom, float top, float near, float far)
Generates a frustum matrix with the given bounds.
Mat4 invert()
Returns the inverse of this matrix as a new Mat4. If this matrix is not invertible null will be returned.
static Mat4 lookAt(Vec3 eye, Vec3 center, Vec3 up)
Generates a look-at matrix with the given eye position, focal point and up axis.
Mat4 mul(Mat4 other)
Returns the multiplication of this matrix with the other as a new Mat4.
static Mat4 ortho(float left, float right, float bottom, float top, float near, float far)
Generates an orthogonal projection matrix with the given bounds.
static Mat4 perspective(float left, float right, float bottom, float top, float near, float far)
Generates a perspective projection matrix with the given bounds.
Mat4 rotate(float angleInRadians, Vec3 axis)
Returns the rotation of this matrix by the given angle around the given axis as a new Mat4.
Mat4 rotateX(float angleInRadians)
Returns the rotation of this matrix by the given angle around the X axis as a new Mat4.
Mat4 rotateY(float angleInRadians)
Returns the rotation of this matrix by the given angle around the Y axis as a new Mat4.
Mat4 rotateZ(float angleInRadians)
Returns the rotation of this matrix by the given angle around the Z axis as a new Mat4.
Mat4 scale(Vec3 scale)
Returns the scaled matrix as a new Mat4.
Mat4 translate(Vec3 translation)
Returns the translated matrix as a new Mat4.
Mat4 transpose()
Returns the transpose of this matrix as a new Mat4.
static Mat4 fromQuat(Quat q)
Generates a 4x4 rotation matrix from the given quaternion.
static Mat4 fromRotationTranslation(Quat rotation, Vec3 translation)
Generates a matrix representing the given rotation and translation. This is much faster than setting the transformations individually.
static Mat4 wrap(Float32Array data)
Returns a new Mat4 wrapper around the given Float32Array. Note: Changes to the returned Mat4 will also change the data in the array!

Box

The Box type represents a bounding box with a stored minimum and maximum point. Unlike the math types the methods of the Box object are mutable and, when applicable, return the same instance of the Box.

attribute Float32Array data
The underlying typed array that this Box wraps.
attribute Vec3 min
Mutable accessor to the minimum point of this bounding box.
attribute Vec3 max
Mutable accessor to the maximum point of this bounding box.
Constructor ()
Creates a new empty Box with min set to MAX_VALUE and max set to MIN_VALUE.
Constructor (Box other)
Creates a new Box which is a copy of the given Box.
Box clone()
Returns a new clone of this bounding box.
Box copy(Box other)
Copies the minimum and maximum points from the other bounding box into this one.
Box copyMin(Box other)
Copies only the minimum point from the given Box.
Box copyMax(Box other)
Copies only the maximum point from the given Box.
Box extend(Box other)
Expands this box to also enclose the given box. This method respects axis alignment if both boxes are axis aligned.
Box setEmpty()
Resets this box to the empty state.
boolean isEmpty()
Returns true if the box is empty. Empty is defined as any box whose minimum point is greater than its maximum.
Vec3 center()
Returns the center of this box as a new Vec3.
Vec3 size()
Returns the size of this box as a new Vec3.
Vec3 extent()
Returns the extent of this box as a new Vec3, defined as half of its size.
Box transformAxisAligned(Mat4 mat)
Transforms this box with the given transformation matrix. This box will remain axis-aligned.
Box transform(Mat4 mat)
Transforms this box with the given transformation matrix. This method does not enforce axis alignment./dd>
float longestSide()
Returns the length of the longest side of this box.
boolean intersects()
Ray r
optional Object opt
If opt.dist exists then the distance to the intersection point will be written into this field. If the ray does not intersect then this field will hold Infinity
Returns true if the given ray intersects this box.
boolean contains(Vec3 point)
Returns true if the given point is inside the box.
DOMString toString()
A human readable string representation of this box.
DOMString toDOMString()
Returns a space-seperated string representation for use in XML3D element attributes or value elements.

Ray

The Ray type represents a ray with an origin and a direction. Unlike the math types Rays are mutable and methods will return the same instance, if applicable.

attribute Float32Array data
The underlying typed array that this Ray wraps.
attribute Vec3 origin
Mutable accessor to the origin point of this ray.
attribute Vec3 direction
Mutable accessor to the direction of this ray. Assignments should always be normalized.
Constructor ()
Creates a new Ray with origin [0,0,0] and direction [0,0,-1]
Constructor (Ray other)
Creates a new Ray which is a copy of the given Ray.
Ray clone()
Returns a new clone of this ray.
Ray copy(Ray other)
Copies the origin and direction from the other ray into this one.
Ray copyOrigin(Ray other)
Copies only the origin from the given Ray.
Ray copyMax(Ray other)
Copies only the direction from the given Ray.
Box setFromOriginDirection(Vec3 origin, Vec3 direction)
Sets the origin and direction of this ray to the given values.
boolean intersects()
Box box
optional Object opt
If opt.dist exists then the distance to the intersection point will be written into this field. If the ray does not intersect then this field will hold Infinity
Returns true if this ray intersects the given box.
DOMString toString()
A human readable string representation of this ray.

Events

Mouse and Keyboard Events

The following event listeners are available on all pickable elements as well as the group element and the xml3d element: The event received by these listeners is a standard HTML5 MouseEvent or KeyboardEvent respectively. As in normal HTML, event listeners may be added to the element through an appropriate on[eventName] attribute or through JavaScript using element.addEventListener(...).
Listeners registered through an attribute must use the following format: "myListenerFunction(event)"

FrameDrawn

attribute float detail.timeStart
The system time at the beginning of the frame draw.
attribute float detail.timeEnd
The system time at the end of the frame draw.
attribute float detail.renderTimeInMilliseconds
The total time taken to render this frame. Includes time spent updating the scene state and any XFlow data processing.
attribute int detail.count.objects
The total number of distinct meshes drawn in this frame after applying frustum culling (if enabled).
attribute int detail.count.primitives
The total number of primitives drawn in this frame after applying frustum culling (if enabled).