Migration Guide from Ventuz 4 to Ventuz 5

If upgrading from Ventuz 4 to Ventuz 5 there are some (breaking) changes in functionality and work-flow to be considered. These changes can be grouped in three categories:

• Removed functionality which causes major differences in Ventuz 5 compared to Ventuz 4
• Changes in work-flow when building scenes and configuring a Ventuz Machine
• Changes in scene logic which make scenes behave and/or look slightly different in Ventuz 5 compared to Ventuz 4

To make it clear: Ventuz Designer and Runtime always guarantees Downwards Compatibility and thus is always able to load scenes and presentations created in former Ventuz versions.

Migration Helper and Resolve Mechanism

Ventuz helps to find and resolve nodes in a scene that are removed, deprecated or changed for this version. The Scene Statistics' Issues Tab lists nodes that cause errors or issues. The same time, these nodes are marked in Hierarchy and Content Editor with a red or orange frame - depending on the error level. The node's tooltip gives a hint too.

The context menu of the node - Click  to open it - will show an Auto-Resolve Issue entry if Ventuz can resolve it automatically. This will replace the node with it's new version when possible. Auto-Resolve is usually possible for nodes that have a counterpart in the new version and are not bound to other nodes.

Removed Features

Removed Nodes

These are nodes which do not work anymore as their functionality has been removed:

• HitTest
• Key
• MouseOver

Deprecated Nodes

These are nodes which are not available in the Toolbox anymore but are still working when loaded from scenes created in Ventuz 4:

• ViewListener
• View
• RenderTarget
• RenderTarget Reference
• Projection (Field of View, Orthogonal, Perspective)
• Viewport/Background
• Texture
• BlurTexture Glow
• BlurTexture Simple
• SoundSource 3D
• View (Orbit, LookAt, Camera)
• Vertex Fog
• Pixel Fog
• PixelSpace
• Viewport/Background
• Overlay Rectangle
• All hard-coded Shader nodes
• Text Buffer
• Images to CubeTexture
• Image to BumpMap
• Image to Texture
• ImageLoader
• Texture Generator
• All Image Filter nodes
• All Image Transform nodes
• 2D Mapping
• 3D Mapping
• Strip Mapper
• VR Camera
• OSC Image

Removed Render Engine Features

Through the deprecated Texture Node, the following features are available but won't work:

• The old bump-mapping feature with Bump00, Bump01, Bump10, Bump11, LumaOffset and LumaScale. The Ventuz5 material system can use proper normal mapping with every material.
• DMapOffset: This feature was intended for presampled displacement mapping. The Ventuz5 material system supports proper displacement mapping with every material.
• TextureSet: This feature was intended for multi element textures. It is useless since Ventuz does not allow creation of multi element textures. The whole concept was superseded quickly after it's invention by multiple render targets.

Changes in Work-flow

When building new scenes in Ventuz 5 you have to consider some changes in workflow to achieve certain results:

• You always need at least one Layer to build a scene.
• Use Layers instead Viewport nodes.
• Use 3D Layer in 'Offscreen' Layout mode instead of Rendertarget nodes.
• The new Camera node combines View and Projection parameters.
• Only one active Camera per Layer is now allowed.
• Some Content node like the Texture provider can now be dragged to Hierarchy Editor - they are then automatically bound to a new Material node.
• The functionality of the Overlay Rectangle node has been replaced by the new Background node.
• The new Main Animation is a global (not restricted to containers) animation entity.
• The Stage Editor has been spit to Stage Editor and Scene Tree Editor.
• Importing VZAs now happens via Scene -> Open.
• To import geometry use the Geometry Import nodes.
• A single Material node can now handle multiple texture stages.

Changes in Scene Logic

New Text Layout Engine

Before Ventuz 5 font loading and text layout was based on a mix of Windows GDI & WPF functionality. This sometimes prevented some fonts from being loaded and lay out correctly. Another big issue was the support of complex script languages like Arabic and Hindi: text in these languages was not always displayed correctly. To solve these problems Ventuz 5 now utilizes DirectWrite. The change of the font layout engine causes some more or less small changes in the text layout and character positioning.

Here are the differences in the new text layout. On the left it the text output of Ventuz 4, on the right Ventuz 5. It's important to note that all these differences do not apply to all fonts. Most of the fonts will be identical or close to the same as in Ventuz 4!

Line Spacing: for some fonts the line distance and base-line may differ between Ventuz 4 and Ventuz 5

Line Spacing in multi-font text: with the Enriched Block Text node one can mix different fonts in one text. In Ventuz 4 the line distance was only based on the parameters of the first font. In Ventuz 5 every used font is taken into account for line distance calculations.

Scaling: when scaling text in the Enriched Block Text node the line distance was not scaled, this is changed for Ventuz 5.

Line Trimming: in Ventuz 4 words which where too long for a single line where trimmed, in Ventuz 5 the exceeding characters are wrapped to the next line.

Trailing Space Character: in Ventuz 5 trailing space characters are trimmed whereas they where handled as normal characters in Ventuz 4.

Wrapping: due to slightly different character positioning wrapping might be different as text might exceed boundings earlier or later.

Monospace: monospace layout for non-monospace fonts needs a special layout routine and the average character width taken as reference may differ to Ventuz 4. This may result in a different character spacing in Ventuz 5.

Justification: Ventuz 5, respectively DirectWrite performs an inter-character space modification to justify text, Ventuz 4 just increased the inter-word space.

Center Alignment: Ventuz 5 has a slightly different calculation of center-aligned text.

Kerning: For some fonts (e.g. Arial) character pair kerning cannot be disabled anymore.

Character Wrapping mode: wrapping test in 'Character' mode does not work with Windows 7 as this DirectWrite function is only available from Windows 8.1 on.

Texture Mapping: Due to slightly different font metric parameter used by DirectWrite the texture mapping on the character may look slightly different.

Animating Text Effect Layers

In Ventuz 4, animations like rotation and scaling letters do not apply the correct origin for the transformation. Ventuz 5 fixes this, resulting in a change. This is only for effect layers, the plain layer has always been animated correctly.

Light Attenuation

Light attenuation, the way it is calculated how lights get dimmer with distance, has changed depending on the engine type

• Legacy and Standard with Legacy Light: The attenuation model, same as Ventuz 4. This model does not create realistic lighting, can not be scaled, does not fade out at range limit and is not intuitive. Use this for compatibility with Ventuz 4.
• Standard: attenuation is controlled only by radius and light strength. Creates better results, can be scaled with world, does fade out at range limit and is intuitive.
• HDR: Is physically correct, can be scaled with world, does fade out at range limit and is intuitive. But it will be notably slower, not because of the math, but because the render targets are twice as big.

Alpha Blending

In Ventuz 4 the source/destination color in the separate alpha section was interpreted differently between AMD and NVIDIA GPU's.

In Ventuz 5 all references to source / dest color in the separate alpha section are changed to references to source / dest alpha. This is how NVidia interprets this. This is also for future DX11 compatibility.

Copyright 2022 Ventuz Technology