Mark-up

                <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

        <mesh src="printable-teapot.stl"></mesh>
        

Data compositing

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.

       <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>
      

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) {
               ...
            }
          });
        

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
          }
        

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];
               }
            }
          }
        

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.

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>
           

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

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.

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

        <view></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>
       

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.

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

        <light></light>
       

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.

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>
          

            <!-- 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>
          

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.

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.

          <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>
        

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.

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

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.

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>
        

        <mesh>
            <!-- "positions" contains the original data 1.0 0.0 0.0 ... -->
           <data src="#originalData"></data>
        </mesh>
        

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:

• The type attribute of the mesh element
• The type attribute of the assetmesh element

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

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.

        wrap := <wrap-mode> <wrap-mode>?
        wrap-mode := repeat | clamp
      

        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
      

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.

        <texture name="diffuseTexture" wrap="repeat clamp" filter="nearest linear">
          <img src="../stone.jpg"/>
        </texture>
      

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.

Triangle

Attribute name: triangles

WebGL primitive: TRIANGLE

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

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

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

Linestrip

Attribute name: linestrips

WebGL primitive: LINE_STRIP

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

Points are drawn from a list of vertex positions, which each position being drawn as a single point.

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>
      

Matte

URN: urn:xml3d:material:matte

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

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

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 Lights

URN: urn:xml3d:light:point

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

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

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.

Perspective

URN: urn:xml3d:view:perspective

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

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.