http://xml3d.org/2009/xml3dThis specification defines the features and syntax for XML3D, an extension to HTML5 to allow interactive three-dimensional graphics graphics.
The aim is to create a web standard that is easy to learn by web designers and web programmers without deep knowledge about 3D programming. This is the main difference to approaches like WebGL and O3D. In contrast to these imperative techniques, XML3D attempts to achieve maximum compatibility with both HTML5 and XHTML. Many of XML3D's facilities are modeled directly after HTML and SVG, including its use of CSS, its approach to event handling, and its approach to the Document Object Model.
XML3D allows several graphical objects: triangle meshes, lines, point etc. Graphical objects can be grouped, styled and transformed. The feature set also includes a simple and unified shading system that is independent of source language, target architecture and rendering engine without sacrificing runtime performance (not yet available in this version).
Sophisticated applications of XML3D are possible through the use of a supplemental scripting language which accesses the Document Object Model (DOM), providing complete access to all elements, attributes and properties. A rich set of event handlers such as 'onmouseover' and 'onclick' can be assigned to any 3D object or to a group of 3D objects. Because of its compatibility and leveraging of other Web standards, features like scripting can be done on XHTML and XML3D elements simultaneously within the same web page.
The work on XML3D and its specification is still work in progress. XML3D is a project of the Computer Graphics Lab of the Saarland University, the DFKI and the Intel Visual Computing Institute. For more information about XML3D and our integration into Mozilla Browser and WebKit please visit the XML3D website and see our XML3D paper.
In a stand-alone XML3D document, the xml3d element is the root element of the XML file. It also can be embedded inline as a fragment within a parent XML document. In this case, the standard XML namespace rules apply to indicate which elements belong to which namespace.
Example for a stand-alone XML3D document:
<xml3d width="300" height="200" xmlns="http://xml3d.org/2009/xml3d">
<group>
<mesh>
...
</mesh>
</group>
</xml3d>
Example for a XML3D embedded into XHTML:
<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xml3d="http://xml3d.org/2009/xml3d">
<head>
<title>A simple Mesh embedded into XHTML</title>
</head>
<body>
<div style="color: red">
<xml3d:xml3d id="myXml3d">
<xml3d:defs>
<xml3d:data id="mySimpleMesh">
<xml3d:int name="index">0 1 2 1 2 3</xml3d:int>
<xml3d:float3 name="position">-1.0 -1.0 0.0 1.0 -1.0 0.0 -1.0 1.0 0.0 1.0 1.0 0.0</xml3d:float3>
<xml3d:float3 name="normal">0.0 0.0 1.0 0.0 0.0 1.0 0.0 0.0 1.0 0.0 0.0 1.0</xml3d:float3>
<xml3d:float2 name="texcoord">0.0 1.0 1.0 1.0 0.0 0.0 1.0 0.0</xml3d:float2>
</xml3d:data>
</xml3d:defs>
<xml3d:mesh src="#mySimpleMesh" type="triangles"/>
</xml3d:xml3d>
</div>
</body>
</html>
The background of the rendering area can be defined using the CSS2 Background properties. The initial value of the background is transparent. If the xml3d element is embedded in some other rendering (like HTML) the background of the parent box's shines through, otherwise the background is black.
| Name | Type | Default Value | Description |
|---|---|---|---|
| height | <int> | "600" | The height of the xml3d canvas in pixels. |
| width | <int> | "800" | The width of the xml3d canvas in pixels. |
| activeView | <IDREF > | "" | Reference to the active view element. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
| EventAttributes | onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, onkeyup |
interface XML3DXml3dElement : XML3DElement, EventAttributes { // Attributes attribute int height; attribute int width; // Methods XML3DVec3 createXML3DVec3(); XML3DRotation createXML3DRotation(); XML3DMatrix createXML3DMatrix(); XML3DRay createXML3DRay(); XML3DElement getElementByPoint(in int x, in int y); }
The elements data, mesh, shader, and lightshader are data containers that combine all contained value elements (int, float, float2, float3, float4, float4x4, bool, and texture) into a data table - a map with the name attribute of the value element as a unique key and the content of the value element as value. Value elements can be direct children of the data container or part of another data element that is either a child of the data container or referred via the src attribute.
In case multiple value elements with the same name are part of a data container, only one key-value-pair is included into the resulting named data table, according to the following rules:
| Name | Type | Default Value | Description |
|---|---|---|---|
| map | <string> | "" | TODO: Documentation |
| expose | <string> | "" | TODO: Documentation |
| src | <IDREF > | "" | Reference to another data element or data file as URI. Can be a location (URL) to a data file or an xml3d data element. If src is defined, all child elements are ignored. Thus, the data table defined by the referred content is reused directly. |
| script | <IDREF > | "" | Reference to an xflow script as URI. Can be a location (URL) or one of the pre-defined scripts as URN. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DDataElement : XML3DNestedDataContainerElement { }
All elements that are inside a defs section can be referenced by either elements in the scene graph or by other elements in an arbitrary defs section of the XML3D document. The defs element is similar to the SVG 'defs' element. It is recommended to define referenced elements inside a defs block to increase readability and understandability, even if some elements could also be defined directly inside the scene graph.
Elements that are descendants of a defs element are not rendered directly. defs may appear as child of the xml3d or group element.
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DDefsElement : XML3DElement { }
The local matrix of a group node is calculated as:
Mcss * MreferenceWhere
| Name | Type | Default Value | Description |
|---|---|---|---|
| visible | <boolean> | "true" | If "false", the element and all it's children are not taken into account during rendering. This flag does not affect children referenced from other parts of the scene graph. |
| transform | <IDREF > | "" | Reference to an element that can provide a 3D transformation (i.e. transform) |
| shader | <IDREF > | "" | Reference to an element that can provide a surface shader (i.e. shader) |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
| EventAttributes | onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, onkeyup |
interface XML3DGroupElement : XML3DGraphElement { // Methods XML3DMatrix getLocalMatrix(); }
This is very generic description of a 3D mesh. It clusters a number of data fields and binds them to a certain name. The interpretation of these data fields is job of the currently active shader. Only connectivity information is required to build the primitives defined by the type attribute:
| Name | Type | Default Value | Description |
|---|---|---|---|
| visible | <boolean> | "true" | If "false", the element and all it's children are not taken into account during rendering. This flag does not affect children referenced from other parts of the scene graph. |
| type | <string> | "triangles" | The type of geometric primitive described by this mesh element. |
| src | <IDREF > | "" | Reference to another data element or data file as URI. Can be a location (URL) to a data file or an xml3d data element. If src is defined, all child elements are ignored. Thus, the data table defined by the referred content is reused directly. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
| EventAttributes | onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, onkeyup |
interface XML3DMeshElement : XML3DGeometryElement { // Attributes readonly attribute DOMString type; }
The center attribute specifies a translation offset from the origin of the local coordinate system (0,0,0). The rotation attribute specifies a rotation of the coordinate system. The scale field specifies a non-uniform scale of the coordinate system. Scale values may have any value: positive, negative (indicating a reflection), or zero. A value of zero indicates that any child geometry shall not be displayed. The scaleOrientation specifies a rotation of the coordinate system before the scale (to specify scales in arbitrary orientations). The scaleOrientation applies only to the scale operation. The translation field specifies a translation to the coordinate system.
The resulting matrix M that represents the element's coordinate system is calculated by a series of intermediate transformations. In matrix transformation notation, where C (center), SR (scaleOrientation), T (translation), R (rotation), and S (scale) are the equivalent transformation matrices, the resulting matrix is calculated as:
M = T * C * R * SR * S * -SR * -C
| Name | Type | Default Value | Description |
|---|---|---|---|
| translation | <XML3DVec3> | "0 0 0" | The translation part of the transformation. |
| scale | <XML3DVec3> | "1 1 1" | The scaling part of the transformation. |
| rotation | <XML3DRotation> | "0 0 1 0" | The rotation part of the transformation. |
| center | <XML3DVec3> | "0 0 0" | Origin for scale and rotation. |
| scaleOrientation | <XML3DRotation> | "0 0 1 0" | Rotational orientation for scale. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DTransformElement : XML3DTransformProviderElement { // Attributes attribute XML3DVec3 translation; attribute XML3DVec3 scale; attribute XML3DRotation rotation; attribute XML3DVec3 center; attribute XML3DRotation scaleOrientation; }
The shader element connects arbitrary shader attributes with some shader code. The shader code is referenced with the script reference. The shader attributes are bound to the shader using the bind mechanism.
The URI syntax is used to define the shader script. This can be either a URL pointing to a script location in- or outside the current resource or a URN pointing to a XML3D standard shader. Following XML3D fixed-function shaders are defined:
Example:
<shader id="red" script="urn:xml3d:shader:phong">
<float3 name="diffuseColor">1 0 0</float3>
</shader>
| Name | Type | Default Value | Description |
|---|---|---|---|
| script | <IDREF > | "" | Reference to the shader script as URI. Can be a location (URL) or one of the pre-defined shaders as URN. TODO: Should be of type "AnyURI" |
| src | <IDREF > | "" | Reference to another data element or data file as URI. Can be a location (URL) to a data file or an xml3d data element. If src is defined, all child elements are ignored. Thus, the data table defined by the referred content is reused directly. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DShaderElement : XML3DSurfaceShaderProviderElement { }
The light source location and orientation is influenced by the scene graph transformation hierarchy. The radiation characteristics of the light source is defined by the referenced lightshader (s. shader attribute). The light can be dimmed using the intensity attribute and can be switched on/off using the visible attribute. If global is set to 'false', the light source will only light the objects that is contained in its parent group or xml3d element. Otherwise it will illuminate all the objects in its scene graph.
| Name | Type | Default Value | Description |
|---|---|---|---|
| visible | <boolean> | "true" | If "false", the element and all it's children are not taken into account during rendering. This flag does not affect children referenced from other parts of the scene graph. |
| shader | <IDREF > | "" | Reference to a lightshader element. |
| global | <boolean> | "false" | If 'false', the light source will only light the children of it's parent node. |
| intensity | <float> | "1" | Will be multiplied with the light source contribution. It is possible to 'dim' the light using values below 1 or to brighten it up using values above 1. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
| EventAttributes | onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, onkeyup |
interface XML3DLightElement : XML3DGraphElement { // Attributes attribute boolean global; attribute float intensity; }
The lightshader element connects arbitrary light shader attributes with a light shader code. The light shader code is referenced via the script reference. The shader attributes are bound to the shader using the data mechanism.
The URI syntax is used to define the light shader script. This can be either a URL pointing to a script location in- or outside the current resource or a URN pointing to a XML3D standard light shader. Following XML3D fixed-function light shaders are defined:
Example:
<lightshader id="myLight" script="urn:xml3d:lightshader:point">
<float3 name="color">1 1 0.8</float3>
<float3 name="attenuation">1 0 0</float3>
</lightshader>
| Name | Type | Default Value | Description |
|---|---|---|---|
| script | <IDREF > | "" | Reference to the shader script as URI. Can be a location (URL) or one of the pre-defined shaders as URN. TODO: Should be of type "AnyURI" |
| src | <IDREF > | "" | Reference to another data element or data file as URI. Can be a location (URL) to a data file or an xml3d data element. If src is defined, all child elements are ignored. Thus, the data table defined by the referred content is reused directly. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DLightShaderElement : XML3DLightShaderProviderElement { }
User agents must interpret the contents of the element as the values. The values of the array are separated with whitespace characters only.
Example:
<float>1.0 2 -3.1415 20090.0098</float>
| Name | Type | Default Value | Description |
|---|---|---|---|
| name | <string> | "" | The name to bind the data field to. This could be for example a shader field. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DFloatElement : XML3DDataSourceElement { // Attributes attribute FloatArray value; }
User agents must interpret the contents of the element as the values. The values of the array are separated with whitespace characters only. The number of elements must be a multiple of 2.
Example:
<float2>1.0 0.0 0.5 0.5 0.25 0</float2>
| Name | Type | Default Value | Description |
|---|---|---|---|
| name | <string> | "" | The name to bind the data field to. This could be for example a shader field. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DFloat2Element : XML3DDataSourceElement { // Attributes attribute Float2Array value; }
User agents must interpret the contents of the element as the values. The values of the array are separated with whitespace characters only. The number of elements must be a multiple of 3.
Example:
<float3>1.0 0.0 -0.25 0.5 0.3 -5.23</float3>
| Name | Type | Default Value | Description |
|---|---|---|---|
| name | <string> | "" | The name to bind the data field to. This could be for example a shader field. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DFloat3Element : XML3DDataSourceElement { // Attributes attribute Float3Array value; }
User agents must interpret the contents of the element as the values. The values of the array are separated with whitespace characters only. The number of elements must be a multiple of 4.
Example:
<float4>2.21 -5.0 -0.25 0.5 0.3 -5.23 200 20.20</float4>
| Name | Type | Default Value | Description |
|---|---|---|---|
| name | <string> | "" | The name to bind the data field to. This could be for example a shader field. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DFloat4Element : XML3DDataSourceElement { // Attributes attribute Float4Array value; }
| Name | Type | Default Value | Description |
|---|---|---|---|
| name | <string> | "" | The name to bind the data field to. This could be for example a shader field. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DFloat4x4Element : XML3DDataSourceElement { // Attributes attribute Float4x4Array value; }
User agents must interpret the contents of the element as the values. The values of the array are separated with whitespace characters only.
Example:
<int>0 1 2 0 3 4 1 3 5</int>
| Name | Type | Default Value | Description |
|---|---|---|---|
| name | <string> | "" | The name to bind the data field to. This could be for example a shader field. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DIntElement : XML3DDataSourceElement { // Attributes attribute IntArray value; }
User agents must interpret the contents of the element as the values. The boolean true is encoded as text value 'true', the boolean false is encoded as text value 'false'. There are only whitespace characters between the boolean values of an array.
Example:
<bool>true true false true</bool>
| Name | Type | Default Value | Description |
|---|---|---|---|
| name | <string> | "" | The name to bind the data field to. This could be for example a shader field. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DBoolElement : XML3DDataSourceElement { // Attributes attribute BoolArray value; }
The texture source and its dimensions are defined by the texture element's children. The states how to apply the texture is set via the texture element's attributes. Use the attributes to influence
| Name | Type | Default Value | Description |
|---|---|---|---|
| name | <string> | "" | The name to bind the data field to. This could be for example a shader field. |
| type | <string> | "2D" | Set the dimensions of the texture. |
| filterMin | <string> | "linear" | Specifies how to apply the texture if the area to be textured has fewer pixels than the texture. |
| filterMag | <string> | "linear" | Specifies how to apply the texture if the area to be textured contains more pixels than the texture. |
| filterMip | <string> | "nearest" | Specifies what mipmap level to use, when a minification filter is required for the texture. |
| wrapS | <string> | "clamp_to_edge" | Specifies what happens when the texture coordinates fall outside of the 0.0 to 1.0 range in s direction. |
| wrapT | <string> | "clamp_to_edge" | Specifies what happens when the texture coordinates fall outside of the 0.0 to 1.0 range in t direction. |
| wrapU | <string> | "clamp_to_edge" | Specifies what happens when the texture coordinates fall outside of the 0.0 to 1.0 range in u direction. |
| borderColor | <string> | "" | Specifies what color to use, if wrapping mode is 'border' and texture coordinates fall outside of the 0.0 to 1.0 range. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
interface XML3DTextureElement : XML3DDataSourceElement { // Attributes attribute DOMString type; attribute DOMString filterMin; attribute DOMString filterMag; attribute DOMString filterMip; attribute DOMString wrapS; attribute DOMString wrapT; attribute DOMString wrapU; attribute DOMString borderColor; }
| Name | Type | Default Value | Description |
|---|---|---|---|
| visible | <boolean> | "true" | If "false", the element and all it's children are not taken into account during rendering. This flag does not affect children referenced from other parts of the scene graph. |
| position | <XML3DVec3> | "0 0 0" | The position of the camera in local coordinates. |
| orientation | <XML3DRotation> | "0 0 1 0" | The orientation of the camera relative to the default orientation. In the default position and orientation, the viewer is on the Z-axis looking down the -Z-axis toward the origin with +X to the right and +Y straight up. |
| fieldOfView | <float> | "0.785398" | The fieldOfView field specifies a preferred minimum viewing angle from this viewpoint in radians. A small field of view roughly corresponds to a telephoto lens; a large field of view roughly corresponds to a wide-angle lens. The field of view shall be greater than zero and smaller than pi. The value of fieldOfView represents the minimum viewing angle in any direction axis perpendicular to the view. |
| Group Name | Attributes |
|---|---|
| CoreAttributes | id, class |
| StyleAttributes | style |
| EventAttributes | onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, onkeyup |
interface XML3DViewElement : XML3DGraphElement { // Attributes attribute XML3DVec3 position; attribute XML3DRotation orientation; attribute float fieldOfView; // Methods void setDirection(in XML3DVec3 direction); void setUpVector(in XML3DVec3 up); void lookAt(in XML3DVec3 target); XML3DVec3 getDirection(); XML3DVec3 getUpVector(); XML3DMatrix getViewMatrix(); }
interface XML3DBox :
{
// Attributes
attribute XML3DVec3 min;
attribute XML3DVec3 max;
// Methods
XML3DVec3 size();
XML3DVec3 center();
void makeEmpty();
boolean isEmpty();
}
interface XML3DMatrix :
{
// Attributes
attribute float m11;
attribute float m12;
attribute float m13;
attribute float m14;
attribute float m21;
attribute float m22;
attribute float m23;
attribute float m24;
attribute float m31;
attribute float m32;
attribute float m33;
attribute float m34;
attribute float m41;
attribute float m42;
attribute float m43;
attribute float m44;
// Methods
void setMatrixValue(in string str) raises(DOMException);
XML3DMatrix multiply(in XML3DMatrix secondMatrix);
XML3DMatrix inverse() raises(DOMException);
XML3DMatrix translate(in float x, in float y, in float z);
XML3DMatrix scale(in float scaleX, in float scaleY, in float scaleZ);
XML3DMatrix rotate(in float rotX, in float rotY, in float rotZ);
XML3DMatrix rotateAxisAngle(in float x, in float y, in float z, in float angle);
}
interface XML3DRay :
{
// Attributes
attribute XML3DVec3 origin;
attribute XML3DVec3 direction;
}
interface XML3DRotation :
{
// Attributes
readonly attribute XML3DVec3 axis;
readonly attribute float angle;
// Methods
void setRotation(in XML3DVec3 from, in XML3DVec3 to) raises(DOMException);
void setAxisAngle(in XML3DVec3 axis, in float angle) raises(DOMException);
void setAxisAngleValue(in string str) raises(DOMException);
XML3DMatrix toMatrix();
XML3DVec3 rotateVec3(in XML3DVec3 inputVector);
XML3DRotation interpolate(in XML3DRotation rot1, in float t);
XML3DRotation multiply(in XML3DRotation rot1);
XML3DRotation normalize();
}
interface XML3DVec3 :
{
// Attributes
attribute float x;
attribute float y;
attribute float z;
// Methods
void setVec3Value(in string str) raises(DOMException);
XML3DVec3 add(in XML3DVec3 secondVec);
XML3DVec3 subtract(in XML3DVec3 secondVec);
XML3DVec3 multiply(in XML3DVec3 secondVec);
XML3DVec3 scale(in float factor);
XML3DVec3 cross(in XML3DVec3 secondVec);
float dot(in XML3DVec3 secondVec);
XML3DVec3 negate();
float length();
XML3DVec3 normalize() raises(DOMException);
}