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 getAttribute and setAttribute with 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() changed

getBoundingBox() is no longer available on xml3d, group, mesh and 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 view in <xml3d> elements:

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

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

The <view> element was transformable using its position and orientation attributes. These attributes got removed. Instead, the <view> element is transformable just like <group>, <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 position and 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

The 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 light and mesh. One can set the camera model using the model attribute. Default is urn:xml3d:view:perspective. The fieldofview attribute is replaced by the fovVertical parameter:

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

No <lightshader> anymore

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 script attribute to the lights model attribute (specifying the light model)
• Rename urn:xml3d:lightshader:xxx to urn:xml3d:light:xxx in the light model defintion
• Rename the <lightshader> element to <data>
• Rename the light's shader attribute to src

Spotlight 'falloffAngle' renamed to 'cutoffAngle'

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

The texture attributes to configure the texture sampling were not HTML5 compliant and thus we changed the names and merged some of them:

• warpS and wrapT have 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
• filterMin and filerMag have been merged to filter. Specify the filtering first for minification then for magnification (e.g. filter="linear-mipmap-linear linear").

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>

or

document.querySelector("mesh").style.display = "none";

or (given there is a CSS style selector setting class hidden)

<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 <xml3d>, <group>, <mesh>, and <model>. To migrate from 4.9, just change all occurances of visibility="false" to style="display: none;".

Voilà!

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.

If your scene used the old math types in Javascript it will need to be adjusted to use the new ones instead. All XML3D interfaces (eg. getElementByPoint or getWorldMatrix) now return and expect the new math types.

'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. <data> or <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!