Migration Guide

Ventuz Designer and Runtime always guarantee Downwards Compatibility and thus are always able to load scenes and presentations created in former Ventuz versions.

However, if upgrading from one major Ventuz version to the next, 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
• 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

Ventuz Migration Helper

Since Ventuz 6.0 the folder locations and structures for settings, configurations and caches changed. That's why the new version comes with a small utility located in the intallation folder: VentuzMigrationHelper.exe
This utility allows to copy all according files from the Ventuz 5 locations to the new Ventuz 6 folders. On the first run of the Ventuz 6 installer this utility is started automatically and allows to select the items that should be copied. When the migration has finished a report is presented. This report is located in C:\Users\Public\Documents\Ventuz6\Logs. On every next installer run the utility checks if a migration already has been performed (by checking the existence of the migration report file) and does not show up anymore. But it's possible to start this tool manually and perform a migration again. Files and settings that can be migrated are e.g.:

• Software licenses
• Machine & HW configurations
• Project Settings
• Repositories
• Font & Emoji Caches

Ths tool also allows UI-less operation if it is started with argument -noui. With following startup options it' possible to specify which settings/files should be migrated:
-noui : start without UI
-all : migrate all settings/configs
-des : migrate Designer User Settings
-dir : migrate Director User Settings
-res : migrate Resolution Presets
-mc : migrate Machine Configurations
-id : migrate Custom SystemID
-vms : migrate VMS Settings
-rep : migrate Repositories
-lic : migrate SOFTWARE LICENSES
-fnt : migrate Fonts and Emojis Cache
-ow : overwrite existing files

Removed Features

Removed Nodes

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

• Image To BumpMap

Deprecated Nodes

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

• FFT Analysis - replaced by Analyze Audio node
• Mesh Loader - replaced by Geometry Renderer and Geometry Provider
• Blending - now part of the Material node
• Alpha Blending - now part of the Material node
• Alpha Testing - now part of the Material node
• Point Options - now part of the Material node
• Render Options - now part of the Material node
• Z-Testing - now part of the Material node

Changes in Scene Logic

Subpixel Shift / Half-Pixel Offset

In Ventuz Versions prior to Ventuz 6, there was a half-pixel offset that originated from DirectX9. To work in pixel dimensions and create perfectly aligned graphics, this had to be corrected by shifting the graphics half a pixel up and to the left. For Ventuz 6, the DirectX version was upgraded. DirectX11 does not introduce this offset anymore, thus the user does not have to care about it any longer. In reverse, this means scenes created in Ventuz 5 are now half a pixel off in Ventuz 6.

Asset URI's

Asset URI's have to be in a valid format. In former Ventuz versions, the syntax was not checked very strictly. Especially the hostname could be non-valid. To assure compatibility when connecting to other technologies like javascript or python, asset URI's need a valid syntax.

assets://./path      invalid
assets:///path       valid
assets://host/path   valid

With respect to this, Ventuz Director now creates Asset URI's different to former versions. Before, subfolders inside the Asset folder were used as host names. This could easily lead to invalid URI's when the folder contained non-valid charaters. Now, the host name is empty and the folder and subfolders are set as path.

assets://subfolder/file.xml     before
assets:///subfolder/file.xml    now

HLSL 5: How To Rewrite Shaders for the HLSL Node

The HLSL node is based on Microsofts Effect Framework. Unfortunately, DX9 shaders (shader model 1.0 to 3.0) will not run on DirectX11. The effect framework has been updated to version 11 so it generates shader model 5.0 shaders, as required for DirectX11. This introduces many incompatibilities with the HLSL source code in the HLSL node.

Here is an overview of what needs to be changed:

Position and normal are float3

DirectX9 allowed to define position and normal as float4. The system would automatically set the w value of the position to 1.0 and the w value of the normal to 0 when the vertex format did only provide x, y and z. This will not happen in DX11:

• specify position and normal as float3
• when doing the matrix multiply, extend the vectors to float4 with a proper value for w.

Vertex Formats

In DirectX9 it was allowed to have the vertex format in the shader to be different than the vertex format of the vertex buffer. A conversion step was applied automatically. This is not allowed in DirectX11 anymore since it added overhead and complexity to the graphics pipeline.

Ventuz detects the required vertex format in a rather crude way by scanning the source for certain names, assuming these names are used as vertex shader semantics.

If your source contains the word "BINORMAL", we use

float4x4 Mat  : WORLDVIEWPROJECTION;

struct VS_INPUT
{
    float3 Position : POSITION;
    float3 Normal : NORMAL;
    float3 Tangent : TANGENT;
    float3 Bitangent : BINORMAL;
    float2 Uv0 : TEXCOORD0;
};

Otherwise, if your source contains the word "TANGENT", we use

float4x4 Mat  : WORLDVIEWPROJECTION;

struct VS_INPUT
{
    float3 Position : POSITION;
    float3 Normal : NORMAL;
    float4 Tangent : TANGENT;    // 'w' contains sign of bitangent
    float2 Uv0 : TEXCOORD0;
};

You are supposed to calculate the Bitangent like this:

float3 bitangent = cross(Normal,Tangent.xyz)*Tangent.w;

Otherwise, we use

float4x4 Mat  : WORLDVIEWPROJECTION;

struct VS_INPUT
{
    float3 Position : POSITION;
    float3 Normal : NORMAL;
    float2 Uv0 : TEXCOORD0;
};

Make sure you use one of these three templates.

Passing Variables from Vertex to Pixel Shader

DirectX9 allowed mismatching declarations of vertex shader outputs and pixel shader inputs. This causes additional overhead when matching vertex and pixel shaders. So in DirectX11, the pixel shader input variables, in type and semantics, must match the vertex shader output variables.

• The Vertex shader may output more variables than the pixel shader reads, but the variables the pixel shader reads must match in type and semantic name, in the right order, starting at the beginning.
• Semantic names may be anything, not just TEXCOORD(X).
• System Values (like POSITION) should be added after the normal variables. This is the most common problem.

Textures must be Tied to a Sampler

DirectX9 had a fixed mapping between 16 textures and 16 samplers. DirectX11 allows for 128 textures and 16 samplers, so it requires a variable mapping between textures and samplers. This is enforced by the effect compiler.

For every texture, you must provide a sampler that is bound to the texture.

New DirectX 11 Keywords

Since we are now compiling for shader model 5.0, the technique keyword must be replaced by technique11 and the shader models must be updated from xs_3_0 to xs_5_0

State Blocks (other than Sampler State)

In DirectX9, every state was set individually. This was very inefficient, so in DirectX11 state is divided into 3 state blocks:

• Blending State
• Depth & Stencil State
• Rasterization State

Please consult the effect framework documentation on how to define and set these states.

A state cannot be set partial when changing one value (like the culling in the rasterization state), the whole state block has to be specified and set.

Sampler State

DirectX11 handles sampler states the same as the other state blocks, but we added code that allows partial update of the sampler state, with defaults taken from the sampler as set by Ventuz nodes.

Please note that many sampler state settings have changed in state and meaning. For instance, MinFilter, MagFilter and MipFilter are no longer set individually but at once in a single setting called Filter.

Binding Textures and HDR

There are three ways textures and samplers can be bound to a shader:

• Explicitly binding a texture as property:
  • Texture is explicitly bound
  • Sampler must be specified in HLSL source
  • Automatic sRGB to Linear conversion is always on in HDR mode
• Specifying bind points with register keyword
  • Texture and sampler are taken from the Ventuz nodes.
  • Sampler settings may be overridden one by one in the HLSL code
  • Automatic sRGB to Linear conversion is done when specified in the Ventuz nodes (only in HDR, of course).
• Not Specifying anything
  • There is an internal counter of what texture and sampler where last set with one of the above methods. The next texture and sampler slot is used.
  • Sampler settings may be overridden one by one in the HLSL code
  • Automatic sRGB to Linear conversion is done when specified in the Ventuz nodes (only in HDR, of course).

It is recommended to use register keyword and set the texture with normal Ventuz nodes.

System Values

Shader Model 3.0 defined a couple of special semantics, like POSITION for vertex shader output and COLOR for pixel shader outputs. In Shader Model 5.0, these are called System Values and are all prefixed with SV_. POSITION changes to SV_Position and Color changes to SV_Target (yes, really). See the HLSL documentation for a full list of system values and how to translate them.

Since the compiler is used in compatibility mode, you need not use the old names, but we recommend it.

No Disassembly

There is no official way to disassemble the shaders created by the Effect Framework 11.

Copyright 2022 Ventuz Technology