XML3D Specification
Unofficial Draft 15 June 2020
Editors:Kristian SonsChristian SchlinkmannAuthors:Felix Klein, Intel Visual Computing InstituteKristian Sons, DFKIChristian Schlinkmann, DFKI
This document is licensed under a Creative Commons Attribution 3.0 License.
Abstract
This document defines the 5th revision of XML3D, an extension to HTML5 for describing interactive 3D scenes.
Status of This Document
This document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.
1. Introduction
1.1 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.
1.2 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].
1.3 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 is an extension to [HTML5].
- XML3D reuses [HTML5] elements, e.g. the
<img>
element to define texture data. - XML3D content can be styled with [CSS2], i.e. XML3D supports all relevant style properties.
- XML3D defines [DOM] interfaces for scripting. All XML3D elements derive from the
HTMLElement
DOM interface. - XML3D leverages [UIEvents] as its event system and supports all relevant events available in HTML. Additionally, it supports all relevant event attributes.
- XML3D adopts the
<defs>
element from [SVG].
XML3D uses [URI]s, in particular URNs for identifiying predefined models and URLs for identifing resources in the same or in external documents.
2. Concepts
2.1 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
- from mark-up, i.e. from value elements and
- from references to an
- intra-document data element
- external resource
NOTETo 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.
2.1.1 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.EXAMPLE 1
<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>
2.1.2 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.EXAMPLE 2
<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.
2.1.3 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.NOTEA 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.
2.1.4 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.
- A subsequent value element overrides previous ones.
- Local value elements override referenced data sources.
- Entries in the output of a referenced data table override entries of a previously referenced data table.
- 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.EXAMPLE 3
<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>
2.1.5 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.EXAMPLE 4
<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>
2.2 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.
2.2.1 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:EXAMPLE 5
<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:EXAMPLE 6
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) { ... } });
NOTEAs 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 }
NOTEFields 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:EXAMPLE 7
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]; } } }
3. 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.NOTEOther properties may affect XML3D elements in the future. Good candidates include the visible
and pointer-events
properties.
3.1 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:noneThis 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:EXAMPLE 8
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:EXAMPLE 9
$("#myMesh").hide(); $(".walls").toggle();
NOTEBe 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.
3.2 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.NOTESome 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.NOTESome 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.
3.3 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:autoThis 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:EXAMPLE 10
<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.EXAMPLE 11
<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>
4. The elements of XML3D
4.1 Kinds of elements
4.1.1 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.NOTEIn 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.EXAMPLE 12
<!-- 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>
4.1.2 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:EXAMPLE 13
<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
:EXAMPLE 14
<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>
4.1.3 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:EXAMPLE 15
<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
:EXAMPLE 16
<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>
4.1.4 Pickable elements
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:EXAMPLE 17
<group onmousedown="myMouseDownListener(event)"> <group> <mesh onmouseup="myMouseUpListener(event)" type="triangles"></mesh> </group> </group>
NOTEObject visibility may affect whether or not mouse event listeners are triggered. See the Style section on visibility for more information.
4.2 The root element
4.2.1 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.
interface XML3DXml3dElement : HTMLElement { attribute unsigned long width; attribute unsigned long height; readonly attribute boolean complete; attribute DOMString view; attribute Function onframedrawn; attribute Function onload; HTMLElement? getElementByPoint (unsigned long x, unsigned long y, optionalVec3
hitPoint, optionalVec3
hitNormal); HTMLElement? getElementByRay (Ray
ray, optionalVec3
hitPoint, optionalVec3
hitNormal);Box
getLocalBoundingBox ();Box
getWorldBoundingBox ();Ray
generateRay (unsigned long x, unsigned long y); };
4.2.1.1 Attributes
complete
of type boolean, readonlyReturns true if all resources of the root element have been completely downloaded and rendered; otherwise, returns false.height
of type unsigned longVertical dimensiononframedrawn
of type FunctionEvent listener to be executed whenever a new frame has been drawn. Is passed a FrameDrawn
event.onload
of type FunctionEvent 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.NOTEThis event may be preceeded by one or more FrameDrawn
events as XML3D continues to redraw the scene even as external resources are being loaded.view
of type DOMStringThe view IDL attribute must reflect the respective content attribute of the same name.width
of type unsigned longHorizontal dimension
4.2.1.2 Methods
generateRay
Uses WebGL unProject to generate a new ray from the given x,y window coordinates.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
x | unsigned long | ✘ | ✘ | The x coordinate relative to the top left of the browser window |
y | unsigned long | ✘ | ✘ | The y coordinate relative to the top left of the browser window |
Return type: Ray
getElementByPoint
Returns the element at the point with window coordinates x,y if there is a scene element; otherwise, returns null.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
x | unsigned long | ✘ | ✘ | The x coordinate relative to the top left of the browser window |
y | unsigned long | ✘ | ✘ | The y coordinate relative to the top left of the browser window |
hitPoint |
| ✘ | ✔ | If provided this vector will be filled with the position of the hit point in world space. |
hitNormal |
| ✘ | ✔ | If provided this vector will be filled with the normal of the hit point in world space. |
Return type: HTMLElement
, nullablegetElementByRay
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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
ray |
| ✘ | ✘ | |
hitPoint |
| ✘ | ✔ | If provided this vector will be filled with the position of the hit point in world space. |
hitNormal |
| ✘ | ✔ | If provided this vector will be filled with the normal of the hit point in world space. |
Return type: HTMLElement
, nullablegetLocalBoundingBox
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.No parameters.Return type: Box
getWorldBoundingBox
Returns the bounding box of the scene in world space.No parameters.Return type: Box
4.3 Scene elements
4.3.1 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.EXAMPLE 18
<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>
interface XML3DGroupElement : HTMLElement { attribute DOMString transform; attribute DOMString material;Mat4
getWorldMatrix ();Mat4
getLocalMatrix ();Box
getLocalBoundingBox ();Box
getWorldBoundingBox (); };
4.3.1.1 Attributes
material
of type DOMStringAccepts a URI fragment referencing a material element. Material is inherited from the parent group if this attribute is not present.transform
of type DOMStringAccepts a URI fragment referencing a transform element. Alternatively a transformation may be defined with CSS through the style attribute.
4.3.1.2 Methods
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.No parameters.Return type: Box
getLocalMatrix
Returns the local transformation matrix of this group element (does not include parent transformations).No parameters.Return type: Mat4
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.No parameters.Return type: Box
getWorldMatrix
Returns the transformation matrix of this group element in world space (includes parent transformations).No parameters.Return type: Mat4
4.3.2 The view
element
Categories:Data elementTransformable 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.NOTECurrently, 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:EXAMPLE 19
<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:EXAMPLE 20
<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:EXAMPLE 21
<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>
NOTEXML3D 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.
interface XML3DViewElement : HTMLElement { attribute DOMString model;Mat4
getWorldMatrix ();Mat4
getLocalMatrix ();Mat4
getViewMatrix ();Mat4
getProjectionMatrix (); };
4.3.2.1 Attributes
model
of type DOMStringThe model
IDL attribute must reflect the model content attribute.
4.3.2.2 Methods
getLocalMatrix
Returns the local transformation matrix of this view element (does not include parent transformations).No parameters.Return type: Mat4
getProjectionMatrix
Returns the projection matrix for the frustum defined by this view.No parameters.Return type: Mat4
getViewMatrix
Returns the view matrix of the camera (the matrix used to transform from world to view space).No parameters.Return type: Mat4
getWorldMatrix
Returns the transformation matrix of this view element in world space.No parameters.Return type: Mat4
4.3.3 The light
element
Categories:Data elementTransformable 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.NOTECurrently, 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:EXAMPLE 22
<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:EXAMPLE 23
<light model="urn:xml3d:light:point"> <float3 name="intensity">0.8 0.8 1</float3> </light>
interface XML3DLightElement :XML3DDataElement
{ attribute DOMString model;Mat4
getWorldMatrix ();Mat4
getLocalMatrix (); };
4.3.3.1 Attributes
model
of type DOMStringThe model
IDL attribute must reflect the model content attribute.
4.3.3.2 Methods
getLocalMatrix
Returns the local transformation matrix of this light element (does not include parent transformations).No parameters.Return type: Mat4
getWorldMatrix
Returns the transformation matrix of this light element in world space.No parameters.Return type: Mat4
4.3.4 The mesh
element
Categories:Data elementPickable elementTransformable 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.NOTEA 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:EXAMPLE 24
<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:EXAMPLE 25
<!-- 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:EXAMPLE 26
<!-- 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
EXAMPLE 27
<!-- 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.
interface XML3DMeshElement : HTMLElement { readonly attribute boolean complete; attribute DOMString type; attribute DOMString src; attribute DOMString material; attribute DOMString transform; XML3DDataResult getResult (Array filter); Array getOutputNames ();Mat4
getWorldMatrix ();Mat4
getLocalMatrix ();Box
getLocalBoundingBox ();Box
getWorldBoundingBox (); };
4.3.4.1 Attributes
complete
of type boolean, readonlyReturns true if all external resources required by this mesh have been loaded, false otherwise.material
of type DOMStringURI reference to a material element.src
of type DOMStringURI reference to another data element containing the data for this mesh. Can be a reference to an external document.transform
of type DOMStringURI reference to a transform element.type
of type DOMStringThe primitive type that this mesh uses. Supported values are triangles
, tristrips
, points
, lines
, linestrips
and derived
.
4.3.4.2 Methods
getLocalBoundingBox
Returns the bounding box of this mesh in object space, without any transformations applied.No parameters.Return type: Box
getLocalMatrix
Returns the local transformation matrix of this mesh element (does not include parent transformations).No parameters.Return type: Mat4
getOutputNames
Returns the names of the data fields available to this mesh node.No parameters.Return type: Array
getResult
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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
filter | Array | ✘ | ✘ |
Return type: XML3DDataResult
getWorldBoundingBox
Returns the bounding box of this mesh in world space.No parameters.Return type: Box
getWorldMatrix
Returns the transformation matrix of this mesh element in world space (includes parent transformations).No parameters.Return type: Mat4
4.3.5 The model
element
Categories:Data elementPickable elementTransformable 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:EXAMPLE 28
<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:EXAMPLE 29
<model src="myExternalAsset.xml#myAsset"> <assetmesh name="hat" material="#aNewMaterialDefinedLocally"></assetmesh> </model>
NOTEMaterials 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
:EXAMPLE 30
<!-- 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.
interface XML3DModelElement : HTMLElement { attribute DOMString src; attribute DOMString material; attribute DOMString transform;Mat4
getWorldMatrix ();Mat4
getLocalMatrix ();Box
getLocalBoundingBox ();Box
getWorldBoundingBox (); };
4.3.5.1 Attributes
material
of type DOMStringURI reference to a material element. This material will only be used for objects that do not define their own material inside the asset
.src
of type DOMStringURI reference to an asset element that this model
should instantiate.transform
of type DOMStringURI reference to a transform element.
4.3.5.2 Methods
getLocalBoundingBox
Returns the bounding box of this model without any parent transformations applied.No parameters.Return type: Box
getLocalMatrix
Returns the local transformation matrix of this model element (does not include parent transformations).No parameters.Return type: Mat4
getWorldBoundingBox
Returns the bounding box of this model in world space, including parent transformations.No parameters.Return type: Box
getWorldMatrix
Returns the transformation matrix of this model in world space, including parent transformations.No parameters.Return type: Mat4
4.4 Definition Areas
4.4.1 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.EXAMPLE 31
<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>
4.5 Property elements
4.5.1 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:EXAMPLE 32
<material model="urn:xml3d:material:phong"> <float3 name="diffuseColor">0 0 1</float3> <texture name="diffuseTexture"> <img src="../stone.jpg"/> </texture> </material>
interface XML3DMaterialElement : XML3DDataElement
{
attribute DOMString model;
};
4.5.1.1 Attributes
model
of type DOMStringThe model
IDL attribute must reflect the model content attribute.
4.5.2 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.
interface XML3DTransformElement : HTMLElement { attributeAxisAngle
scaleorientation; attributeAxisAngle
rotation; attributeVec3
translation; attributeVec3
scale; attributeVec3
center; };
4.5.2.1 Attributes
center
of type Vec3
The center point of this transformation.rotation
of type AxisAngle
The rotation component of this transformation. In axis-angle form [x,y,z,a] with the angle expressed in radians.scale
of type Vec3
The scale component of this transformation. Note: non-uniform scaling and negative values are allowed.scaleorientation
of type AxisAngle
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.translation
of type Vec3
The translation component of this transformation.
4.6 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.
4.6.1 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.
interface XML3DAssetElement : HTMLElement { attribute DOMString src; };
4.6.1.1 Attributes
src
of type DOMStringA URI to another asset that this one should extend.
4.6.2 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.
interface XML3DAssetdataElement : HTMLElement { attribute DOMString name; attribute DOMString includes; };
4.6.2.1 Attributes
includes
of type DOMStringA space separated list of names corresponding to other assetdata elements that this one should extend.name
of type DOMStringThe name of this assetdata element. The name is scoped to the surrounding asset element and may not be duplicated within this scope.
4.6.3 The assetmesh
element
Categories:Data elementTransformable 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.EXAMPLE 33
<assetmesh name="exampleMesh" style="transform: translate3d(0px, 0px, 10px)" type="triangles" material="#exampleMaterial"> <data src="#myMeshData"></data> <assetdata src="#someMoreMeshData"></assetdata> </assetmesh>
interface XML3DAssetmeshElement : HTMLElement { attribute DOMString name; attribute DOMString includes; attribute DOMString type; attribute DOMString material; attribute DOMString transform; };
4.6.3.1 Attributes
includes
of type DOMStringA space separated list of names corresponding to other assetmesh
or assetdata elements that this one should extend.material
of type DOMStringURI reference to a material element.name
of type DOMStringThe name of this assetmesh
element. The name is scoped to the surrounding asset element and may not be duplicated within this scope.transform
of type DOMStringURI reference to a transform element.type
of type DOMStringThe primitive type of this assetmesh
. Supported values are triangles
, tristrips
, points
, lines
, linestrips
, and derived
4.7 Data and dataflow elements
4.7.1 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:EXAMPLE 34
<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:EXAMPLE 35
<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:EXAMPLE 36
<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).
interface XML3DDataElement : HTMLElement { readonly attribute boolean complete; attribute DOMString compute; attribute DOMString filter; attribute DOMString src; XML3DDataResult getResult (Array filter); Array getOutputNames (); };
4.7.1.1 Attributes
complete
of type boolean, readonlyReturns true if all external resources required by this data have been loaded, false otherwise.compute
of type DOMStringA Javascript-like statement that can invoke an Xflow compute operator on a set of input data. See the compute operator section for more information.filter
of type DOMStringMay 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.src
of type DOMStringAccepts 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.
4.7.1.2 Methods
getOutputNames
Returns the names of the data fields provided by this data element.No parameters.Return type: Array
getResult
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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
filter | Array | ✘ | ✘ |
Return type: XML3DDataResult
4.7.2 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:EXAMPLE 37
<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:EXAMPLE 38
<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.
interface XML3DDataflowElement : HTMLElement { attribute DOMString out; readonly attribute boolean complete; XML3DDataResult getResult (Array filter); Array getOutputNames (); };
4.7.2.1 Attributes
complete
of type boolean, readonlyReturns true if all external resources required by this dataflow have been loaded, false otherwise.out
of type DOMStringA 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.
4.7.2.2 Methods
getOutputNames
Returns the names of the data fields provided by this data element.No parameters.Return type: Array
getResult
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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
filter | Array | ✘ | ✘ |
Return type: XML3DDataResult
4.7.3 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 4×4 matrices.
interface XML3DFloatValueElement : HTMLElement { attribute DOMString name; attribute boolean param; attribute float key; void setScriptValue (Float32Array value); };
4.7.3.1 Attributes
key
of type floatA keyframe value to assist in defining animated values. A script may, for example, interpolate the data between successive keys.name
of type DOMStringThe name of the value element. A good name should be a semantic description of the data that this element holds.param
of type booleanMarks 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.
4.7.3.2 Methods
setScriptValue
A high performance setter to set the data of this value element directly through JavaScript.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
value | Float32Array | ✘ | ✘ |
Return type: void
4.7.4 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.
interface XML3DIntValueElement : HTMLElement { attribute DOMString name; attribute boolean param; attribute float key; void setScriptValue (Int16Array value); };
4.7.4.1 Attributes
key
of type floatA keyframe value to assist in defining animated values. A script may, for example, interpolate the data between successive keys.name
of type DOMStringThe name of the value element. A good name should be a semantic description of the data that this element holds.param
of type booleanMarks 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.
4.7.4.2 Methods
setScriptValue
A high performance setter to set the data of this value element directly through JavaScript.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
value | Int16Array | ✘ | ✘ |
Return type: void
4.7.5 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
).
interface XML3DBoolValueElement : HTMLElement { attribute DOMString name; attribute boolean param; attribute float key; void setScriptValue (Int16Array value); };
4.7.5.1 Attributes
key
of type floatA keyframe value to assist in defining animated values. A script may, for example, interpolate the data between successive keys.name
of type DOMStringThe name of the value element. A good name should be a semantic description of the data that this element holds.param
of type booleanMarks 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.
4.7.5.2 Methods
setScriptValue
A high performance setter to set the data of this value element directly through JavaScript.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
value | Int16Array | ✘ | ✘ |
Return type: void
4.7.6 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:EXAMPLE 39
<!-- 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>
interface XML3DStringValueElement : HTMLElement { attribute DOMString name; attribute boolean param; attribute float key; void setScriptValue (Array value); };
4.7.6.1 Attributes
key
of type floatA keyframe value to assist in defining animated values. A script may, for example, interpolate the data between successive keys.name
of type DOMStringThe name of the value element. A good name should be a semantic description of the data that this element holds.param
of type booleanMarks 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.
4.7.6.2 Methods
setScriptValue
A high performance setter to set the data of this value element directly through JavaScript.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
value | Array | ✘ | ✘ |
Return type: void
4.7.7 The texture
element
Categories:Value elementContent model:One or more img
, video
, or canvas
elementsThe 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.NOTE
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”.NOTE
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:EXAMPLE 40
<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 stateThe 1D state means the children elements define a 1D texture each.The 2D keyword, which maps to the 2D stateThe 2D state means the children elements defines a 2D texture.The 3D keyword, which maps to the 3D stateThe 3D state means the children elements defines a 3D texture.The auto stateThe 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.
interface XML3DTextureElement : HTMLElement { attribute DOMString wrap; attribute DOMString filter; attribute DOMString name; attribute boolean param; attribute DOMString type; };
4.7.7.1 Attributes
filter
of type DOMStringThe filter
IDL attribute must reflect the respective content attribute of the same name.name
of type DOMStringRequired. The name of the texture as defined by the material shader.param
of type booleanIf 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.type
of type DOMStringThe type
IDL attribute must reflect the content attribute of the same name, limited to only known values.wrap
of type DOMStringThe wrap
IDL attribute must reflect the respective content attribute of the same name.
5. Predefined models
5.1 Predefined primitive types
5.1.1 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.EXAMPLE 41
<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>
5.1.2 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.EXAMPLE 42
<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.
5.1.3 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.
5.1.4 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.EXAMPLE 43
<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.
5.1.5 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.NOTECurrently to change the size of the drawn points, or to draw them as textured sprites, it is necessary to define a custom material shader.
5.1.6 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.EXAMPLE 44
<mesh type="derived"> <string name="type">triangles</string> ... </mesh>
5.2 Predefined material models
5.2.1 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”.
5.2.2 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); }
5.2.3 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); }
5.3 Predefined light models
5.3.1 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.
5.3.2 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.
5.3.3 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.
5.4 Predefined view models
This section describes the currently available predefined view models.
5.4.1 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.
5.4.2 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.
6. 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:EXAMPLE 45
XML3D.materials.register("my-material", { ...material definition... });
and may then be referenced through the model attribute of a material element:EXAMPLE 46
<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:EXAMPLE 47
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:EXAMPLE 48
<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.NOTEBe 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:EXAMPLE 49
<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>
7. 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.
interface options { string getValue (string key); void setValue (string key, string value); Array getKeys (); void addObserver (string key, function observer); void removeObserver (function observer); void resetValue (string key); void setOptionsFromQuery (); };
7.1 Methods
addObserver
Adds a change observer to the option with the given key. Supports the ‘*’ wildcard to observe all options.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
key | string | ✘ | ✘ | |
observer | function | ✘ | ✘ |
Return type: void
getKeys
Returns an array of all available option keys.No parameters.Return type: Array
getValue
Returns the current value of the option with the matching key.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
key | string | ✘ | ✘ |
Return type: string
removeObserver
Removes the given change observer from all keys.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
observer | function | ✘ | ✘ |
Return type: void
resetValue
Resets the value of the option with the matching key to the default value.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
key | string | ✘ | ✘ |
Return type: void
setOptionsFromQuery
Parses the page URL for option keys and values in the standard query form. Done once automatically on page load.No parameters.Return type: void
setValue
Set the option with the given key to the given value.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
key | string | ✘ | ✘ | |
value | string | ✘ | ✘ |
Return type: void
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! |
NOTEThese options can also be set through URL queries by appending xml3d-
, like so: ?xml3d-loglevel=debug
8. 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
.NOTEA response with no Content-Type
header at all will not be handled and will generate an error message.
9. 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.
9.1 Vec2
A two component vector object.
[ Constructor, Constructor (float x, float y), Constructor (Float32Array other), Constructor (Vec2
other)] interface Vec2 { attribute Float32Array data; attribute float x; attribute float y; staticVec2
fromDOMString (DOMString str); DOMString toDOMString (Vec2
vec);Vec2
add (Vec2
other);Vec2
clone (); float dist (Vec2
other);Vec2
divide (Vec2
other); float dot (Vec2
other); float length ();Vec2
lerp (Vec2
other, float weight);Vec2
max (Vec2
other);Vec2
min (Vec2
other);Vec2
mul (Vec2
other);Vec2
mul (Mat2
other);Vec2
mul (Mat3
other);Vec2
mul (Mat4
other);Vec2
negate ();Vec2
normalize (); staticVec2
random (optional float scale);Vec2
scale (float scale);Vec2
sub (Vec2
other); staticVec2
wrap (Float32Array data); };
9.1.1 Constructors
Vec2
Creates a new identity Vec2 [0,0]
No parameters.Vec2
Creates a new Vec2 from the given values.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
x | float | ✘ | ✘ | |
y | float | ✘ | ✘ |
Vec2
Creates a new Vec2 which is a copy of the values in the passed array.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other | Float32Array | ✘ | ✘ |
Vec2
Creates a new Vec2 which is a copy of the given Vec2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.1.2 Attributes
data
of type Float32ArrayThe underlying typed array that this Vec2 wraps.x
of type floatProvides mutable access to the first component of this vector.y
of type floatProvides mutable access to the second component of this vector.
9.1.3 Methods
add
Returns the component wise addition of the two vectors as a new Vec2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec2
clone
Returns a new copy of this Vec2.No parameters.Return type: Vec2
dist
The distance between this and the given vector.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: float
divide
Returns the component wise division of the two vectors as a new Vec2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec2
dot
The dot product of this and the given vector.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: float
fromDOMString
, staticCreates a new Vec2 object from the space-separated string representation as used in XML3D element attributes.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
str | DOMString | ✘ | ✘ |
Return type: Vec2
length
Returns the length of this vector.No parameters.Return type: float
lerp
Returns a linear interpolation between the two vectors as a new Vec2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ | |
weight | float | ✘ | ✘ | Interpolation amount between the two vectors, range of [0,1]. |
Return type: Vec2
max
Returns a new Vec2 that contains the component wise maximum of the two vectors.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec2
min
Returns a new Vec2 that contains the component wise minimum of the two vectors.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec2
mul
Returns the component wise multiplication of the two vectors as a new Vec2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec2
mul
Returns the transformation of this vector with the given 2×2 matrix as a new Vec2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec2
mul
Returns the transformation of this vector with the given 3×3 matrix as a new Vec2. The third vector component is implicitly ‘1’.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec2
mul
Returns the transformation of this vector with the given 4×4 matrix as a new Vec2. The third vector component is implicitly ‘0’, the fourth ‘1’.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec2
negate
Returns the component wise negation of this vector as a new Vec2.No parameters.Return type: Vec2
normalize
Returns the normalized representation of this vector as a new Vec2.No parameters.Return type: Vec2
random
, staticGenerates a random vector with the given scale, or a unit vector if omitted.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale | float | ✘ | ✔ |
Return type: Vec2
scale
Returns the scaled vector as a new Vec2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale | float | ✘ | ✘ |
Return type: Vec2
sub
Returns the component wise subtraction of the two vectors as a new Vec2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec2
toDOMString
Converts a Vec2 into the space-seperated string representation used in XML3D element attributes.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
vec |
| ✘ | ✘ |
Return type: DOMString
wrap
, staticReturns a new Vec2 wrapper around the given Float32Array. Note: Changes to the returned Vec2 will also change the data in the array!
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Float32Array | ✘ | ✘ |
Return type: Vec2
9.2 Vec3
A three component vector object.
[ Constructor, Constructor (float x, float y, float z), Constructor (Float32Array other), Constructor (Vec3
other)] interface Vec3 { attribute Float32Array data; attribute float x; attribute float y; attribute float z; staticVec3
fromDOMString (DOMString str); DOMString toDOMString (Vec3
vec);Vec3
add (Vec3
other);Vec3
clone ();Vec3
cross (Vec3
other); float dist (Vec3
other);Vec3
divide (Vec3
other); float dot (Vec3
other); float length ();Vec3
lerp (Vec3
other, float weight);Vec3
max (Vec3
other);Vec3
min (Vec3
other);Vec3
mul (Vec3
other);Vec3
mul (Mat3
other);Vec3
mul (Mat4
other);Vec3
mul (Quat
q);Vec3
negate ();Vec3
normalize (); staticVec3
random (optional float scale);Vec3
reciprocal ();Vec3
scale (float scale);Vec3
sub (Vec3
other);Vec3
transformDirection (Mat4
mat); staticVec3
wrap (Float32Array data); };
9.2.1 Constructors
Vec3
Creates a new identity Vec3 [0,0,0]
No parameters.Vec3
Creates a new Vec3 from the given values.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
x | float | ✘ | ✘ | |
y | float | ✘ | ✘ | |
z | float | ✘ | ✘ |
Vec3
Creates a new Vec3 which is a copy of the values in the passed array.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other | Float32Array | ✘ | ✘ |
Vec3
Creates a new Vec3 which is a copy of the given Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.2.2 Attributes
data
of type Float32ArrayThe underlying typed array that this Vec3 wraps.x
of type floatProvides mutable access to the first component of this vector.y
of type floatProvides mutable access to the second component of this vector.z
of type floatProvides mutable access to the third component of this vector.
9.2.3 Methods
add
Returns the component wise addition of the two vectors as a new Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec3
clone
Returns a new copy of this Vec3.No parameters.Return type: Vec3
cross
Returns the cross product of this and the other vector as a new Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec3
dist
The distance between this and the given vector.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: float
divide
Returns the component wise division of the two vectors as a new Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec3
dot
The dot product of this and the given vector.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: float
fromDOMString
, staticCreates a new Vec3 object from the space-separated string representation as used in XML3D element attributes.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
str | DOMString | ✘ | ✘ |
Return type: Vec3
length
Returns the length of this vector.No parameters.Return type: float
lerp
Returns a linear interpolation between the two vectors as a new Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ | |
weight | float | ✘ | ✘ | Interpolation amount between the two vectors, range of [0,1]. |
Return type: Vec3
max
Returns a new Vec3 that contains the component wise maximum of the two vectors.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec3
min
Returns a new Vec3 that contains the component wise minimum of the two vectors.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec3
mul
Returns the component wise multiplication of the two vectors as a new Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec3
mul
Returns the transformation of this vector with the given 3×3 matrix as a new Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec3
mul
Returns the transformation of this vector with the given 4×4 matrix as a new Vec3. The fourth vector component is implicitly ‘1’
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec3
mul
Returns the transformation of this vector with the given quaternion as a new Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
q |
| ✘ | ✘ |
Return type: Vec3
negate
Returns the component wise negation of this vector as a new Vec3.No parameters.Return type: Vec3
normalize
Returns the normalized representation of this vector as a new Vec3.No parameters.Return type: Vec3
random
, staticGenerates a random vector with the given scale, or a unit vector if omitted.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale | float | ✘ | ✔ |
Return type: Vec3
reciprocal
Returns the component wise reciprocal of this vector as a new Vec3.No parameters.Return type: Vec3
scale
Returns the scaled vector as a new Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale | float | ✘ | ✘ |
Return type: Vec3
sub
Returns the component wise subtraction of the two vectors as a new Vec3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec3
toDOMString
Converts a Vec3 into the space-seperated string representation used in XML3D element attributes.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
vec |
| ✘ | ✘ |
Return type: DOMString
transformDirection
Returns the transformation of this vector with the given 4×4 matrix as a new Vec3. The fourth vector component is implicitly ‘0’
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mat |
| ✘ | ✘ |
Return type: Vec3
wrap
, staticReturns a new Vec3 wrapper around the given Float32Array. Note: Changes to the returned Vec3 will also change the data in the array!
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Float32Array | ✘ | ✘ |
Return type: Vec3
9.3 Vec4
A four component vector object.
[ Constructor, Constructor (float x, float y, float z, float w), Constructor (Float32Array other), Constructor (Vec4
other)] interface Vec4 { attribute Float32Array data; attribute float x; attribute float y; attribute float z; attribute float w; staticVec4
fromDOMString (DOMString str); DOMString toDOMString (Vec4
vec);Vec4
add (Vec4
other);Vec4
clone (); float dist (Vec4
other);Vec4
divide (Vec4
other); float dot (Vec4
other); float length ();Vec4
lerp (Vec4
other, float weight);Vec4
max (Vec4
other);Vec4
min (Vec4
other);Vec4
mul (Vec4
other);Vec4
mul (Mat4
other);Vec4
negate ();Vec4
normalize (); staticVec4
random (optional float scale);Vec4
scale (float scale);Vec4
sub (Vec4
other);Vec4
transformQuat (Quat
q); staticVec4
wrap (Float32Array data); };
9.3.1 Constructors
Vec4
Creates a new identity Vec4 [0,0,0,0]
No parameters.Vec4
Creates a new Vec4 from the given values.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
x | float | ✘ | ✘ | |
y | float | ✘ | ✘ | |
z | float | ✘ | ✘ | |
w | float | ✘ | ✘ |
Vec4
Creates a new Vec4 which is a copy of the values in the passed array.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other | Float32Array | ✘ | ✘ |
Vec4
Creates a new Vec4 which is a copy of the given Vec4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.3.2 Attributes
data
of type Float32ArrayThe underlying typed array that this Vec4 wraps.w
of type floatProvides mutable access to the fourth component of this vector.x
of type floatProvides mutable access to the first component of this vector.y
of type floatProvides mutable access to the second component of this vector.z
of type floatProvides mutable access to the third component of this vector.
9.3.3 Methods
add
Returns the component wise addition of the two vectors as a new Vec4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec4
clone
Returns a new copy of this Vec4.No parameters.Return type: Vec4
dist
The distance between this and the given vector.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: float
divide
Returns the component wise division of the two vectors as a new Vec4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec4
dot
The dot product of this and the given vector.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: float
fromDOMString
, staticCreates a new Vec4 object from the space-separated string representation as used in XML3D element attributes.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
str | DOMString | ✘ | ✘ |
Return type: Vec4
length
Returns the length of this vector.No parameters.Return type: float
lerp
Returns a linear interpolation between the two vectors as a new Vec4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ | |
weight | float | ✘ | ✘ | Interpolation amount between the two vectors, range of [0,1]. |
Return type: Vec4
max
Returns a new Vec4 that contains the component wise maximum of the two vectors.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec4
min
Returns a new Vec4 that contains the component wise minimum of the two vectors.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec4
mul
Returns the component wise multiplication of the two vectors as a new Vec4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec4
mul
Returns the transformation of this vector with the given 4×4 matrix as a new Vec4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec4
negate
Returns the component wise negation of this vector as a new Vec4.No parameters.Return type: Vec4
normalize
Returns the normalized representation of this vector as a new Vec4.No parameters.Return type: Vec4
random
, staticGenerates a random vector with the given scale, or a unit vector if omitted.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale | float | ✘ | ✔ |
Return type: Vec4
scale
Returns the scaled vector as a new Vec4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale | float | ✘ | ✘ |
Return type: Vec4
sub
Returns the component wise subtraction of the two vectors as a new Vec4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Vec4
toDOMString
Converts a Vec4 into the space-seperated string representation used in XML3D element attributes.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
vec |
| ✘ | ✘ |
Return type: DOMString
transformQuat
Returns the transformation of this vector with the given quaternion as a new Vec4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
q |
| ✘ | ✘ |
Return type: Vec4
wrap
, staticReturns a new Vec4 wrapper around the given Float32Array. Note: Changes to the returned Vec4 will also change the data in the array!
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Float32Array | ✘ | ✘ |
Return type: Vec4
9.4 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.
[ Constructor, Constructor (float x, float y, float z, float angle), Constructor (Float32Array other), Constructor (AxisAngle
other)] interface AxisAngle { attribute Float32Array data; attributeVec3
axis; attribute float angle; staticAxisAngle
fromDOMString (DOMString str); DOMString toDOMString (AxisAngle
vec);AxisAngle
clone (); staticAxisAngle
fromQuat (Quat
q);Quat
toQuat (); staticAxisAngle
wrap (Float32Array data); };
9.4.1 Constructors
AxisAngle
Creates a new identity AxisAngle [0,0,1,0]
No parameters.AxisAngle
Creates a new AxisAngle from the given values.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
x | float | ✘ | ✘ | |
y | float | ✘ | ✘ | |
z | float | ✘ | ✘ | |
angle | float | ✘ | ✘ |
AxisAngle
Creates a new AxisAngle which is a copy of the values in the passed array.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other | Float32Array | ✘ | ✘ |
AxisAngle
Creates a new AxisAngle which is a copy of the given AxisAngle.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.4.2 Attributes
angle
of type floatProvides mutable access to the angle component. The angle should always be in radians.axis
of type Vec3
Provides mutable access to the axis vector.data
of type Float32ArrayThe underlying typed array that this AxisAngle wraps in the form [x, y, z, angle]
9.4.3 Methods
clone
Returns a new copy of this AxisAngle.No parameters.Return type: AxisAngle
fromDOMString
, staticCreates a new AxisAngle object from the space-separated string representation as used in XML3D element attributes.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
str | DOMString | ✘ | ✘ |
Return type: AxisAngle
fromQuat
, staticCreates a new axis-angle representation of the given quaternion’s rotation.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
q |
| ✘ | ✘ |
Return type: AxisAngle
toDOMString
Converts a AxisAngle into the space-seperated string representation used in XML3D element attributes.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
vec |
| ✘ | ✘ |
Return type: DOMString
toQuat
Creates a new quaternion representation of this AxisAngle’s rotation.No parameters.Return type: Quat
wrap
, staticReturns a new AxisAngle wrapper around the given Float32Array. Note: Changes to the returned AxisAngle will also change the data in the array!
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Float32Array | ✘ | ✘ |
Return type: AxisAngle
9.5 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.
[ Constructor, Constructor (float x, float y, float z, float w), Constructor (Float32Array other), Constructor (Quat
other)] interface Quat { attribute Float32Array data; attribute float x; attribute float y; attribute float z; attribute float w; staticQuat
fromDOMString (DOMString str); DOMString toDOMString (Quat
vec);Quat
add (Quat
other);Quat
clone ();Quat
calculateW ();Quat
conjugate (); float dot (Quat
other);Quat
invert (); float length ();Quat
lerp (Quat
other, float weight);Quat
mul (Quat
other);Quat
normalize ();Quat
rotateX (float angleInRadians);Quat
rotateY (float angleInRadians);Quat
rotateZ (float angleInRadians);Quat
scale (float scale); staticQuat
fromAxisAngle (AxisAngle
a); staticQuat
fromBasis (Vec3
x,Vec3
y,Vec3
z); staticQuat
fromMat3 (Mat3
mat); staticQuat
fromRotationTo (Vec3
from,Vec3
to);Quat
slerp (Quat
other, float weight); staticQuat
wrap (Float32Array data); };
9.5.1 Constructors
Quat
Creates a new identity Quat [0,0,0,1]
No parameters.Quat
Creates a new Quat from the given values.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
x | float | ✘ | ✘ | |
y | float | ✘ | ✘ | |
z | float | ✘ | ✘ | |
w | float | ✘ | ✘ |
Quat
Creates a new Quat which is a copy of the values in the passed array.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other | Float32Array | ✘ | ✘ |
Quat
Creates a new Quat which is a copy of the given Quat.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.5.2 Attributes
data
of type Float32ArrayThe underlying typed array that this Quat wraps.w
of type floatProvides mutable access to the fourth component of this quaternion.x
of type floatProvides mutable access to the first component of this quaternion.y
of type floatProvides mutable access to the second component of this quaternion.z
of type floatProvides mutable access to the third component of this quaternion.
9.5.3 Methods
add
Returns the addition of the two quaternions as a new Quat.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: 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.No parameters.Return type: Quat
clone
Returns a new copy of this Quat.No parameters.Return type: Quat
conjugate
Returns the conjugate of this quaternion as a new Quat. Note: This method should only be used on normalized quaternions!No parameters.Return type: Quat
dot
Returns the dot product of the two quaternions.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: float
fromAxisAngle
, staticGenerates a normalized quaternion representation of the given AxisAngle.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
a |
| ✘ | ✘ |
Return type: Quat
fromBasis
, staticGenerates a normalized quaternion from the given basis vectors, defined as the rotation between the coordinate space defined by these vectors and the standard space.
Return type: Quat
fromDOMString
, staticCreates a new Quat object from a space-separated string representation.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
str | DOMString | ✘ | ✘ |
Return type: Quat
fromMat3
, staticGenerates a normalized quaternion from the given rotation matrix.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mat |
| ✘ | ✘ |
Return type: Quat
fromRotationTo
, staticGenerates a normalized quaternion representing the shortest rotation from one vector to another.
Return type: 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.No parameters.Return type: Quat
length
Returns the magnitude of this quaternion.No parameters.Return type: float
lerp
Returns a linear interpolation between the two quaternions as a new Quat.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ | |
weight | float | ✘ | ✘ | Interpolation amount between the two quaternions, range of [0,1]. |
Return type: Quat
mul
Returns the component wise multiplication of the two quaternions as a new Quat.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Quat
normalize
Returns the normalized representation of this quaternion as a new Quat.No parameters.Return type: Quat
rotateX
Returns a new quaternion representing this one rotated around the X axis by the given angle.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
angleInRadians | float | ✘ | ✘ |
Return type: Quat
rotateY
Returns a new quaternion representing this one rotated around the Y axis by the given angle.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
angleInRadians | float | ✘ | ✘ |
Return type: Quat
rotateZ
Returns a new quaternion representing this one rotated around the Z axis by the given angle.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
angleInRadians | float | ✘ | ✘ |
Return type: Quat
scale
Returns the scaled quaternion as a new Quat. This is identical to Vec4
.scale.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale | float | ✘ | ✘ |
Return type: Quat
slerp
Returns a spherical linear interpolation between the two quaternions as a new Quat.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ | |
weight | float | ✘ | ✘ | Interpolation amount between the two quaternions, range of [0,1]. |
Return type: Quat
toDOMString
Converts a Quat into a space-seperated string representation.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
vec |
| ✘ | ✘ |
Return type: DOMString
wrap
, staticReturns a new Quat wrapper around the given Float32Array. Note: Changes to the returned Quat will also change the data in the array!
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Float32Array | ✘ | ✘ |
Return type: Quat
9.6 Mat2
A 2×2 matrix object.
[ Constructor, Constructor (Float32Array other), Constructor (Mat2
other)] interface Mat2 { attribute Float32Array data; attribute float m11; attribute float m12; attribute float m21; attribute float m22;Mat2
adjoint ();Mat2
clone (); float determinant ();Mat2
invert ();Mat2
mul (Mat2
other);Mat2
rotate (float angleInRadians);Mat2
scale (Vec2
scale);Mat2
transpose (); staticMat2
wrap (Float32Array data); };
9.6.1 Constructors
Mat2
Creates a new identity Mat2.No parameters.Mat2
Creates a new Mat2 which is a copy of the values in the passed array.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other | Float32Array | ✘ | ✘ |
Mat2
Creates a new Mat2 which is a copy of the given Mat2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.6.2 Attributes
data
of type Float32ArrayThe underlying typed array that this Mat2 wraps.m11
of type floatProvides mutable access to the first column of the first row of this matrix.m12
of type floatProvides mutable access to the second column of the first row of this matrix.m21
of type floatProvides mutable access to the first column of the second row of this matrix.m22
of type floatProvides mutable access to the second column of the second row of this matrix.
9.6.3 Methods
adjoint
Computes the adjugate of this matrix as a new Mat2.No parameters.Return type: Mat2
clone
Returns a new copy of this Mat2.No parameters.Return type: Mat2
determinant
Computes the determinant of this matrix.No parameters.Return type: float
invert
Returns the inverse of this matrix as a new Mat2. If this matrix is not invertible null
will be returned.No parameters.Return type: Mat2
mul
Returns the multiplication of this matrix with the other as a new Mat2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Mat2
rotate
Returns the rotation of this matrix by the given angle in radians as a new Mat2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
angleInRadians | float | ✘ | ✘ |
Return type: Mat2
scale
Returns the scaled matrix as a new Mat2.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale |
| ✘ | ✘ |
Return type: Mat2
transpose
Returns the transpose of this matrix as a new Mat2.No parameters.Return type: Mat2
wrap
, staticReturns a new Mat2 wrapper around the given Float32Array. Note: Changes to the returned Mat2 will also change the data in the array!
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Float32Array | ✘ | ✘ |
Return type: Mat2
9.7 Mat3
A 3×3 matrix object.
[ Constructor, Constructor (Float32Array other), Constructor (Mat3
other)] interface Mat3 { attribute Float32Array data; attribute float m11; attribute float m12; attribute float m13; attribute float m21; attribute float m22; attribute float m23; attribute float m31; attribute float m32; attribute float m33;Mat3
adjoint ();Mat3
clone (); float determinant (); staticMat3
fromMat4 (Mat4
mat); staticMat3
fromQuat (Quat
q); staticMat3
normalFromMat4 (Mat4
mat);Mat3
invert ();Mat3
mul (Mat3
other);Mat3
rotate (float angleInRadians);Mat3
scale (Vec3
scale);Mat3
translate (Vec3
translation);Mat3
transpose (); staticMat3
wrap (Float32Array data); };
9.7.1 Constructors
Mat3
Creates a new identity Mat3.No parameters.Mat3
Creates a new Mat3 which is a copy of the values in the passed array.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other | Float32Array | ✘ | ✘ |
Mat3
Creates a new Mat3 which is a copy of the given Mat3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.7.2 Attributes
data
of type Float32ArrayThe underlying typed array that this Mat3 wraps.m11
of type floatProvides mutable access to the first column of the first row of this matrix.m12
of type floatProvides mutable access to the second column of the first row of this matrix.m13
of type floatProvides mutable access to the third column of the first row of this matrix.m21
of type floatProvides mutable access to the first column of the second row of this matrix.m22
of type floatProvides mutable access to the second column of the second row of this matrix.m23
of type floatProvides mutable access to the third column of the second row of this matrix.m31
of type floatProvides mutable access to the first column of the third row of this matrix.m32
of type floatProvides mutable access to the second column of the third row of this matrix.m33
of type floatProvides mutable access to the third column of the third row of this matrix.
9.7.3 Methods
adjoint
Computes the adjugate of this matrix as a new Mat3.No parameters.Return type: Mat3
clone
Returns a new copy of this Mat3.No parameters.Return type: Mat3
determinant
Computes the determinant of this matrix.No parameters.Return type: float
fromMat4
, staticCreates a new Mat3 from the upper-left values of the given 4×4 matrix.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mat |
| ✘ | ✘ |
Return type: Mat3
fromQuat
, staticCreates a new 3×3 rotation matrix from the given quaternion.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
q |
| ✘ | ✘ |
Return type: Mat3
invert
Returns the inverse of this matrix as a new Mat3. If this matrix is not invertible null
will be returned.No parameters.Return type: Mat3
mul
Returns the multiplication of this matrix with the other as a new Mat3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Mat3
normalFromMat4
, staticCreates a 3×3 normal matrix (transpose inverse) from the given 4×4 matrix.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mat |
| ✘ | ✘ |
Return type: Mat3
rotate
Returns the rotation of this matrix by the given angle in radians as a new Mat3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
angleInRadians | float | ✘ | ✘ |
Return type: Mat3
scale
Returns the scaled matrix as a new Mat3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale |
| ✘ | ✘ |
Return type: Mat3
translate
Returns the translated matrix as a new Mat3.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
translation |
| ✘ | ✘ |
Return type: Mat3
transpose
Returns the transpose of this matrix as a new Mat3.No parameters.Return type: Mat3
wrap
, staticReturns a new Mat3 wrapper around the given Float32Array. Note: Changes to the returned Mat3 will also change the data in the array!
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Float32Array | ✘ | ✘ |
Return type: Mat3
9.8 Mat4
A 4×4 matrix object.
[ Constructor, Constructor (Float32Array other), Constructor (Mat4
other)] interface Mat4 { attribute Float32Array data; 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;Mat4
adjoint ();Mat4
clone (); float determinant (); staticMat4
frustum (float left, float right, float bottom, float top, float near, float far);Mat4
invert (); staticMat4
lookAt (Vec3
eye,Vec3
center,Vec3
up);Mat4
mul (Mat4
other); staticMat4
ortho (float left, float right, float bottom, float top, float near, float far); staticMat4
perspective (float left, float right, float bottom, float top, float near, float far);Mat4
rotate (float angleInRadians,Vec3
axis);Mat4
rotateX (float angleInRadians);Mat4
rotateY (float angleInRadians);Mat4
rotateZ (float angleInRadians);Mat4
scale (Vec3
scale);Mat4
translate (Vec3
translation);Mat4
transpose (); staticMat4
fromQuat (Quat
q); staticMat4
fromRotationTranslation (Quat
rotation,Vec3
translation); staticMat4
wrap (Float32Array data); };
9.8.1 Constructors
Mat4
Creates a new identity Mat4.No parameters.Mat4
Creates a new Mat4 which is a copy of the values in the passed array.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other | Float32Array | ✘ | ✘ |
Mat4
Creates a new Mat4 which is a copy of the given Mat4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.8.2 Attributes
data
of type Float32ArrayThe underlying typed array that this Mat4 wraps.m11
of type floatProvides mutable access to the first column of the first row of this matrix.m12
of type floatProvides mutable access to the second column of the first row of this matrix.m13
of type floatProvides mutable access to the third column of the first row of this matrix.m14
of type floatProvides mutable access to the fourth column of the first row of this matrix.m21
of type floatProvides mutable access to the first column of the second row of this matrix.m22
of type floatProvides mutable access to the second column of the second row of this matrix.m23
of type floatProvides mutable access to the third column of the second row of this matrix.m24
of type floatProvides mutable access to the fourth column of the second row of this matrix.m31
of type floatProvides mutable access to the first column of the third row of this matrix.m32
of type floatProvides mutable access to the second column of the third row of this matrix.m33
of type floatProvides mutable access to the third column of the third row of this matrix.m34
of type floatProvides mutable access to the fourth column of the third row of this matrix.m41
of type floatProvides mutable access to the first column of the fourth row of this matrix.m42
of type floatProvides mutable access to the second column of the fourth row of this matrix.m43
of type floatProvides mutable access to the third column of the fourth row of this matrix.m44
of type floatProvides mutable access to the fourth column of the fourth row of this matrix.
9.8.3 Methods
adjoint
Computes the adjugate of this matrix as a new Mat4.No parameters.Return type: Mat4
clone
Returns a new copy of this Mat4.No parameters.Return type: Mat4
determinant
Computes the determinant of this matrix.No parameters.Return type: float
fromQuat
, staticGenerates a 4×4 rotation matrix from the given quaternion.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
q |
| ✘ | ✘ |
Return type: Mat4
fromRotationTranslation
, staticGenerates a matrix representing the given rotation and translation. This is much faster than setting the transformations individually.
Return type: Mat4
frustum
, staticGenerates a frustum matrix with the given bounds.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
left | float | ✘ | ✘ | |
right | float | ✘ | ✘ | |
bottom | float | ✘ | ✘ | |
top | float | ✘ | ✘ | |
near | float | ✘ | ✘ | |
far | float | ✘ | ✘ |
Return type: Mat4
invert
Returns the inverse of this matrix as a new Mat4. If this matrix is not invertible null
will be returned.No parameters.Return type: Mat4
lookAt
, staticGenerates a look-at matrix with the given eye position, focal point and up axis.
Return type: Mat4
mul
Returns the multiplication of this matrix with the other as a new Mat4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Mat4
ortho
, staticGenerates an orthogonal projection matrix with the given bounds.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
left | float | ✘ | ✘ | |
right | float | ✘ | ✘ | |
bottom | float | ✘ | ✘ | |
top | float | ✘ | ✘ | |
near | float | ✘ | ✘ | |
far | float | ✘ | ✘ |
Return type: Mat4
perspective
, staticGenerates a perspective projection matrix with the given bounds.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
left | float | ✘ | ✘ | |
right | float | ✘ | ✘ | |
bottom | float | ✘ | ✘ | |
top | float | ✘ | ✘ | |
near | float | ✘ | ✘ | |
far | float | ✘ | ✘ |
Return type: Mat4
rotate
Returns the rotation of this matrix by the given angle around the given axis as a new Mat4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
angleInRadians | float | ✘ | ✘ | |
axis |
| ✘ | ✘ |
Return type: Mat4
rotateX
Returns the rotation of this matrix by the given angle around the X axis as a new Mat4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
angleInRadians | float | ✘ | ✘ |
Return type: Mat4
rotateY
Returns the rotation of this matrix by the given angle around the Y axis as a new Mat4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
angleInRadians | float | ✘ | ✘ |
Return type: Mat4
rotateZ
Returns the rotation of this matrix by the given angle around the Z axis as a new Mat4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
angleInRadians | float | ✘ | ✘ |
Return type: Mat4
scale
Returns the scaled matrix as a new Mat4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
scale |
| ✘ | ✘ |
Return type: Mat4
translate
Returns the translated matrix as a new Mat4.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
translation |
| ✘ | ✘ |
Return type: Mat4
transpose
Returns the transpose of this matrix as a new Mat4.No parameters.Return type: Mat4
wrap
, staticReturns a new Mat4 wrapper around the given Float32Array. Note: Changes to the returned Mat4 will also change the data in the array!
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
data | Float32Array | ✘ | ✘ |
Return type: Mat4
9.9 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.
[ Constructor, Constructor (Box
other)] interface Box { attribute Float32Array data; attributeVec3
min; attributeVec3
max;Box
clone ();Box
copy (Box
other);Box
copyMin (Box
other);Box
copyMax (Box
other);Box
extend (Box
other);Box
setEmpty (); boolean isEmpty ();Vec3
center ();Vec3
size ();Vec3
extent ();Box
transformAxisAligned (Mat4
mat);Box
transform (Mat4
mat); float longestSide (); boolean intersects (Ray
r, optional Object opt); boolean contains (Vec3
point); DOMString toString (); };
9.9.1 Constructors
Box
Creates a new empty Box with min
set to MAX_VALUE
and max
set to MIN_VALUE
.No parameters.Box
Creates a new Box which is a copy of the given Box.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.9.2 Attributes
data
of type Float32ArrayThe underlying typed array that this Box wraps.max
of type Vec3
Mutable accessor to the maximum point of this bounding box.min
of type Vec3
Mutable accessor to the minimum point of this bounding box.
9.9.3 Methods
center
Returns the center of this box as a new Vec3.No parameters.Return type: Vec3
clone
Returns a new clone of this bounding box.No parameters.Return type: Box
contains
Returns true if the given point is inside the box.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
point |
| ✘ | ✘ |
Return type: boolean
copy
Copies the minimum and maximum points from the other bounding box into this one.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Box
copyMax
Copies only the maximum point from the given Box.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Box
copyMin
Copies only the minimum point from the given Box.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Box
extend
Expands this box to also enclose the given box. This method respects axis alignment if both boxes are axis aligned.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Box
extent
Returns the extent of this box as a new Vec3, defined as half of its size.No parameters.Return type: Vec3
intersects
Returns true if the given ray intersects this box.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
r |
| ✘ | ✘ | |
opt | Object | ✘ | ✔ | 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 |
Return type: boolean
isEmpty
Returns true if the box is empty. Empty is defined as any box whose minimum point is greater than its maximum.No parameters.Return type: boolean
longestSide
Returns the length of the longest side of this box.No parameters.Return type: float
setEmpty
Resets this box to the empty state.No parameters.Return type: Box
size
Returns the size of this box as a new Vec3.No parameters.Return type: Vec3
toString
A human readable string representation of this box.No parameters.Return type: DOMString
transform
Transforms this box with the given transformation matrix. This method does not enforce axis alignment./dd>
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mat |
| ✘ | ✘ |
Return type: Box
transformAxisAligned
Transforms this box with the given transformation matrix. This box will remain axis-aligned.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mat |
| ✘ | ✘ |
Return type: Box
9.10 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.
[ Constructor, Constructor (Ray
other)] interface Ray { attribute Float32Array data; attributeVec3
origin; attributeVec3
direction;Ray
clone ();Ray
copy (Ray
other);Ray
copyOrigin (Ray
other);Ray
copyMax (Ray
other);Box
setFromOriginDirection (Vec3
origin,Vec3
direction); boolean intersects (Box
box, optional Object opt); DOMString toString (); };
9.10.1 Constructors
Ray
Creates a new Ray with origin [0,0,0]
and direction [0,0,-1]
No parameters.Ray
Creates a new Ray which is a copy of the given Ray.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
9.10.2 Attributes
data
of type Float32ArrayThe underlying typed array that this Ray wraps.direction
of type Vec3
Mutable accessor to the direction of this ray. Assignments should always be normalized.origin
of type Vec3
Mutable accessor to the origin point of this ray.
9.10.3 Methods
clone
Returns a new clone of this ray.No parameters.Return type: Ray
copy
Copies the origin and direction from the other ray into this one.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Ray
copyMax
Copies only the direction from the given Ray.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Ray
copyOrigin
Copies only the origin from the given Ray.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
other |
| ✘ | ✘ |
Return type: Ray
intersects
Returns true if this ray intersects the given box.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
box |
| ✘ | ✘ | |
opt | Object | ✘ | ✔ | 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 |
Return type: boolean
setFromOriginDirection
Sets the origin and direction of this ray to the given values.
Return type: Box
toString
A human readable string representation of this ray.No parameters.Return type: DOMString
10. Events
10.1 Mouse and Keyboard Events
The following event listeners are available on all pickable elements as well as the group element and the xml3d element:
- onclick
- ondblclick
- onmousedown
- onmouseup
- onmouseover
- onmousemove
- onmouseout
- onkeypress
- onkeydown
- onkeyup
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(...)
.NOTEListeners registered through an attribute must use the following format: "myListenerFunction(event)"
10.2 FrameDrawn
interface FrameDrawn : CustomEvent { attribute float detail.timeStart; attribute float detail.timeEnd; attribute float detail.renderTimeInMilliseconds; attribute int detail.count.objects; attribute int detail.count.primitives; };
10.2.1 Attributes
detail.count.objects
of type intThe total number of distinct meshes drawn in this frame after applying frustum culling (if enabled).detail.count.primitives
of type intThe total number of primitives drawn in this frame after applying frustum culling (if enabled).detail.renderTimeInMilliseconds
of type floatThe total time taken to render this frame. Includes time spent updating the scene state and any XFlow data processing.detail.timeEnd
of type floatThe system time at the end of the frame draw.detail.timeStart
of type floatThe system time at the beginning of the frame draw.ReSpec
A. References
A.1 Informative references
[CSS2]Bert Bos; Tantek Çelik; Ian Hickson; Håkon Wium Lie et al. W3C. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation. URL: https://web.archive.org/web/20200612205034/https://www.w3.org/TR/CSS2/[CSS3-transforms]Simon Fraser; Dean Jackson; Theresa O’Connor; Dirk Schulze. W3C. CSS Transforms Module Level 1. 14 February 2019. W3C Candidate Recommendation. URL: https://web.archive.org/web/20200612205034/https://www.w3.org/TR/css-transforms-1/[DOM]Anne van Kesteren. WHATWG. DOM Standard. Living Standard. URL: https://web.archive.org/web/20200612205034/https://dom.spec.whatwg.org/[HTML5]Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O’Connor; Silvia Pfeiffer. W3C. HTML5. 27 March 2018. W3C Recommendation. URL: https://web.archive.org/web/20200612205034/https://www.w3.org/TR/html5/[SVG]Jon Ferraiolo. W3C. Scalable Vector Graphics (SVG) 1.0 Specification. 4 September 2001. W3C Recommendation. URL: https://web.archive.org/web/20200612205034/https://www.w3.org/TR/SVG/[UIEvents]Gary Kacmarcik; Travis Leithead; Doug Schepers. W3C. UI Events. 30 May 2019. W3C Working Draft. URL: https://web.archive.org/web/20200612205034/https://www.w3.org/TR/uievents/[URI]T. Berners-Lee; R. Fielding; L. Masinter. IETF. Uniform Resource Identifier (URI): Generic Syntax. January 2005. Internet Standard. URL: https://web.archive.org/web/20200612205034/https://tools.ietf.org/html/rfc3986[WebGL]Dean Jackson; Jeff Gilbert. Khronos. WebGL 2.0 Specification. 12 August 2017. URL: https://web.archive.org/web/20200612205034/https://www.khronos.org/registry/webgl/specs/latest/2.0/[XML]Tim Bray; Jean Paoli; Michael Sperberg-McQueen; Eve Maler; François Yergeau et al. W3C. Extensible Markup Language (XML) 1.0 (Fifth Edition). 26 November 2008. W3C Recommendation. URL: https://web.archive.org/web/20200612205034/https://www.w3.org/TR/xml/[custom-elements]Domenic Denicola. W3C. Custom Elements. 3 May 2018. W3C Note. URL: https://web.archive.org/web/20200612205034/https://www.w3.org/TR/custom-elements/[rfc2045]N. Freed; N. Borenstein. IETF. Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. November 1996. Draft Standard. URL: https://web.archive.org/web/20200612205034/https://tools.ietf.org/html/rfc2045[selectors-api2]Lachlan Hunt. W3C. Selectors API Level 2. 17 October 2013. W3C Note. URL: https://web.archive.org/web/20200612205034/https://www.w3.org/TR/selectors-api2/