Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Migrate to XML3D 5.0
The 5.0 release of XML3D is not backwards compatible to 4.x. We provide the xml3d-4to5 script to help adapt your existing scenes but some manual changes may be necessary too (particularly for XML3D asset files as these are not covered by the script).
Here is a list of changes you have to apply to your scene to migrate to version 5.0:
Change all previously camel-cased attribute names to lowercase
activeview, fieldofview, wraps, wrapt, wrapu, filtermin, filtermax, filtermip, scaleorientation
- You can still use
setAttributewith camel-cased names (eg. setAttribute("fieldOfView", 0.5) ). These will automatically be lowercased in XML3D 5.0
- Element properties (eg. viewElement.fieldOfView) are still camel-cased.
getBoundingBox() is no longer available on
model elements. There are now two separate functions available:
- getLocalBoundingBox() - Get the bounding box of the element in object space
- getWorldBoundingBox() - Get the bounding box of the element in world space (including all parent transformations).
If you are using getBoundingBox() now you should choose one of the two new functions instead, depending on what kind of bounding box you need.
<xml3d> activeView renamed to view
To get rid of unnecessary camel-case attributes, we renamed
activeView to just
<!-- Old way --> <xml3d activeView="#defaultView">...</xml3d> <!-- New way --> <xml3d view="#defaultView">...</xml3d>
Also, the IDL value of view is 'view' now, if no attribute is set. This way, you can get the active view by using querySelector on the
<xml3d> element (selecting first view if no attribute is given):
var xml3d = document.querySelector("xml3d"); var view = xml3d.querySelector(xml3d.view);
<shader> element renamed to
In XML3D we have distinguishable concepts for materials (the former shader element and shade.js) and for vertex and general data processing (Xflow). Both may end up in a generated shader. Thus
<shader> is misleading as it concerns the material aspect only and we decided to rename it to
<material>. The URNs that reference the predefined material models have been renamed accordingly. Additionally, the
script attribute has been renamed to ```model`` because it references the material model to use:
<!-- Old way --> <shader script="urn:xml3d:shader:phong">...</shader> <!-- New way --> <material model="urn:xml3d:material:phong">...</material>
<view> element transformation changed
<view> element was transformable using its
orientation attributes. These attributes got removed. Instead, the
<view> element is transformable just like
<mesh> and other elements using either CSS 3D Transforms or a reference to a
<transform> element or to a dataflow graph using the
<transform> attribute. The old
orientation attributes can easily be transformed:
<!-- Old way --> <view position="1 2 3" orientation="0 1 0 1.57"></view> <!-- New way --> <view style="transform: translate3d(1px, 2px, 3px) rotate3d(0, 1, 0, 90deg);"></view> <!-- or --> <transform id="viewTransform" translation="1 2 3" rotation="0 1 0 1.57"></transform> <view transform="#viewTransform"></view>
<view> element is configurable now
view element used to have a fieldOfView parameter to configure the perspective camera model that was used internally. Alternatively, one could use Xflow to set the projection matrix using the projection attribute.
With 5.0, the view element is configurable similar to
mesh. One can set the camera model using the model attribute. Default is
fieldofview attribute is replaced by the
<!-- Old way --> <view fieldofview="0.87"></view> <!-- New way --> <view> <float name="fovVertical">0.87</float> </view>
The perspective camera model has additional parameters now one can configure (e.g. far, near). The
projection attribute has been removed. Instead there is the
urn:xml3d:view:projective camera model that accepts a
projectionMatrix which can be the result of an Xflow graph:
<view model="urn:xml3d:view:projective"> <float4x4 name="projectionMatrix">...</float4x4> </view>
The definition of lights has changed in XML3D 5.0 (see this issue). The simplest way migrating is to
- Move the value of the lightshader's
scriptattribute to the lights
modelattribute (specifying the light model)
urn:xml3d:light:xxxin the light model defintion
- Rename the
- Rename the light's
Spotlight 'falloffAngle' renamed to 'cutoffAngle'
falloffAngle was renamed to
cutoffAngle. No change to functionality so a simple find/replace is all that's needed to update a scene.
Texture sampling parameters changed
texture attributes to configure the texture sampling were not HTML5 compliant and thus we changed the names and merged some of them:
wrapThave been merged to
wrap. Specify the wrap type (clamp, repeat) for s and t direction in order or just one value for the same wrap type in all directions
filerMaghave been merged to
filter. Specify the filtering first for minification then for magnification (e.g.
Visibility is now set via CSS
Instead of setting the visibility via attribute like this
<mesh src="teapot.json" visibility="false"></mesh>
One can use the CSS
display property now:
<mesh src="teapot.jsons" style="display: none;"></mesh>
document.querySelector("mesh").style.display = "none";
or (given there is a CSS style selector setting class
<mesh src="teapot.jsons" class="hidden"></mesh>
or using jQuery:
$("mesh").hide(); // Hide all meshes $("mesh").toggle(); // Toggle visibility of meshes
Default is to inherit the display value from the parent element. Works for
To migrate from 4.9, just change all occurances of
Datatypes have been replaced
XML3DRotation, XML3DVec3, XML3DBox, XML3DMatrix and XML3DRay are no longer available. New datatypes have been implemented that should be easier to work with and offer more functionality. For a full list and API description of the new math types see the XML3D 5.0 specification.
'src' attribute on Xflow nodes behavior changed
Referencing another Xflow node through the
src attribute no longer causes all child nodes to be ignored. Instead the referenced node is now treated as an implicit first child of the referencing node.
This change shouldn't impact the majority of scenes, but you should check for instances of Xflow elements (eg.
<mesh>) with a
src attribute and having child nodes. To get the same behavior as before simply delete the child nodes in these cases.
'meshTransform' is no longer supported
Before 5.0 it was possible to specify a transformation matrix for a mesh or an assetmesh in the following way:
<mesh> <float4x4 name="meshTransform">1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1</float4x4> </mesh>
This is no longer supported. Instead you should either provide the matrix with a CSS transform:
<mesh style="transform: matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)"> </mesh>
Or using the
transform attribute to reference a
data element that contains a float4x4 with name 'transform':
<data id="myTransform"> <float4x4 name="transform">1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1</float4x4> </data> <mesh transform="#myTransform"></mesh>
Material 'transparency' is now 'opacity'
We've renamed the
transparency parameter of our default materials to
opacity to be more consistent with CSS. This means the value will be inverted ('1' now means fully opaque instead of fully transparent), so when changing the name of the parameter remember to also adapt the value as well!