Kanzi 3.8 migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.7 to Kanzi 3.8.

Transitions between states without animations

In a State Manager when you use transitions that do not have an animation, in Kanzi 3.8 the State Manager sends the Transition Started and Transition Finished messages. If your application relies on not receiving these messages, when you upgrade your application to Kanzi 3.8, modify your application to take into account this change in the functionality.

Changes to skinned meshes

If in your Kanzi application you use skinned meshes, when migrating your application to Kanzi 3.8, update mesh data and transformations of skeleton nodes.

To update only the required items in the Library and keep the values of existing properties, merge the skinned meshes from an fbx or a dae file:

  1. In the Library > Resource Files > 3D Assets right-click a skinned mesh and select Merge 3D Asset File. See Merging 3D assets.

  2. In the Merge tool:

    1. Select the check box next to the skinned mesh.

      This way you update the mesh data.

    2. Select the skeleton nodes whose transformations differ from those in the existing Kanzi Studio project.

    3. In the Merge tool click Resolve to source and then click Merge.

    After merging make sure that your changes to the nodes, such as added properties and modified values, in the imported Scene node, remain the same.

  3. In the vertex shader of the material that you use for the skinned mesh that you merged replace the part of the shader that calculates skinning with the code that works in Kanzi 3.6.8 and in the Shader Source Editor click Save.

    For example, replace

    localToSkinMatrix = kzWorldMatrix * localToSkinMatrix;

vec4 positionWorld = localToSkinMatrix * vec4(kzPosition.xyz, 1.0);
vViewDirection = positionWorld.xyz - kzCameraPosition;
vec4 Norm = mat4(localToSkinMatrix[0],
                 localToSkinMatrix[1],
                 localToSkinMatrix[2],
                 vec4(0.0, 0.0, 0.0, 1.0)) * vec4(kzNormal.xyz, 0.0);
vN = normalize(Norm.xyz);
gl_Position = kzProjectionCameraWorldMatrix * vec4(positionWorld.xyz, 1.0);

    with

    mat4 localToWorldMatrix = kzWorldMatrix * localToSkinMatrix;

vec4 positionWorld = localToWorldMatrix * vec4(kzPosition.xyz, 1.0);
vViewDirection = positionWorld.xyz - kzCameraPosition;
vec3 V = normalize(vViewDirection);
vec4 Norm = mat4(localToWorldMatrix[0],
                 localToWorldMatrix[1],
                 localToWorldMatrix[2],
                 vec4(0.0, 0.0, 0.0, 1.0)) * vec4(kzNormal.xyz, 0.0);
vN = normalize(Norm.xyz);
gl_Position = kzProjectionCameraWorldMatrix * localToSkinMatrix * vec4(kzPosition.xyz, 1.0);

Hardware key handling changes

To handle hardware key input, you must use key manipulators. In Kanzi 3.8 and Key Up messages are replaced with the Key Pressed and Key Released messages.

When you open your project in Kanzi Studio, Kanzi Studio automatically converts projects that use Key Down and Key Up messages with Key Pressed and Key Released messages and adds a Key Manipulator trigger to the node of the message with the key present in the condition. However, Kanzi Studio automatically converts only the Key Down and Key Up messages that use equality sign in their conditions. If in conditions of these message you use operations other that equality, you must manually convert all such key manipulators.

Focus changes

The Screen node is no longer a focus scope that provides focus chain navigation functionality. To use focus chain navigation in your project:

  1. Set either the first node under the Screen node or a node where you want to use focus navigation, to be a focus group or a focus fence

  2. Enable the Focusable property for that node.

See Focus.

Font changes

  • Renamed the Font class to FontRuntime, which now also holds the font style. As a result of this, TextFormat, TextLayouter, and TextShaper now take FontRuntime instead of Font.

  • Removed the Node::FontProperty and replaced its functionality with:

    • Node::FontFamilyProperty

    • FontStyleConcept::WeightProperty

    • FontStyleConcept::StyleProperty

  • Moved and renamed these properties from the TextBlockConcept to the FontStyleConcept class:

    Kanzi 3.7

    Kanzi 3.8

    TextBlockConcept::FontSizeProperty

    FontStyleConcept::SizeProperty

    TextBlockConcept::CharacterSpacingProperty

    FontStyleConcept::CharacterSpacingProperty

    TextBlockConcept::FixedCharacterWidthProperty

    FontStyleConcept::FixedCharacterWidthProperty

    TextBlockConcept::LineSpacingProperty

    FontStyleConcept::LineSpacingProperty

  • Made these changes to the FontManager class:

    • Replaced FontManager::createFont with the functionality of FontManager::getRuntimeFont introduced in Kanzi 3.8.

    • Removed FontManager::getFontFamily. You can get the font family as a resource from the ResourceManager.

    • Removed FontManager::createFontFamily. Use FontFamily::create instead.

  • Moved these functions from TextFormat and TextLayouter classes to the FontStyleDefinition class:

    Kanzi 3.7

    Kanzi 3.8

    TextFormat::setLineSpacing, TextLayouter::setLineSpacing

    FontStyleDefinition::setLineSpacing

    TextFormat::getLineSpacing, TextLayouter::getLineSpacing

    FontStyleDefinition::getLineSpacing

    TextFormat::setCharacterSpacing, TextLayouter::setCharacterSpacing

    FontStyleDefinition::setCharacterSpacing

    TextFormat::getCharacterSpacing, TextLayouter::getCharacterSpacing

    FontStyleDefinition::getCharacterSpacing

    TextFormat::setFixedCharacterWidth, TextLayouter::setFixedCharacterWidth

    FontStyleDefinition::setFixedCharacterWidth

    TextFormat::getFixedCharacterWidth, TextLayouter::getFixedCharacterWidth

    FontStyleDefinition::getFixedCharacterWidth

    TextFormat::setShapingEnabled, TextLayouter::setShapingEnabled

    FontStyleDefinition::setShapingEnabled

Messages changes

  • Removed kzuMessageType. Use AbstractMessageTypeDescriptor instead.

  • Removed the constructor of MessageArguments that takes AbstractMessageType as parameter. To dispatch messages using AbstractMessageType, use Node::dispatchAbstractMessage().

Prefab View node changes

Prefab View nodes no longer recreate the node tree if the Prefab Template property (PrefabProperty) does not change. If your application relies on Kanzi to recreate the node tree on property write, such as with the On Attached trigger, you can force the recreation of the node tree by setting the Prefab Template first to an empty value.

Kanzi Engine plugin metadata changes

Changed the syntax of Kanzi Engine plugin metadata attribute SortingIndex to metadata.sortingIndex. See sortingIndex.

Other changes

  • Moved these headers to new locations:

    Headers

    Kanzi 3.8 location

    Templates:

    • trigger_template.hpp

    <KanziWorkspace>/Engine/include/kanzi/core.ui/template

    Triggers:

    • message_trigger.hpp

    • on_attached_trigger.hpp

    • on_property_changed_trigger.hpp

    • timer_trigger.hpp

    <KanziWorkspace>/Engine/include/kanzi/ui/node_component/trigger

    Actions:

    • dispatch_message_action.hpp

    • forwarding_action.hpp

    • play_animation_action.hpp

    • set_property_action.hpp

    • write_log_action.hpp

    • set_focus_action.hpp

    • move_focus_action.hpp

    <KanziWorkspace>/Engine/include/kanzi/ui/action

    Animation node compoments:

    • animation_player.hpp

    • property_driven_animation_player.hpp

    • property_field_target_interpolation_timeline_playback.hpp

    • property_target_interpolation_timeline.hpp

    • property_target_interpolation_timeline_playback.hpp

    • property_target_interpolator.hpp

    <KanziWorkspace>/Engine/include/kanzi/ui/node_component/animation

  • Flipped the sign of the PanManipulator::MovedMessage delta.

  • Calls in the Mesh and Renderer classes that handle changing either vertex or index data now take as buffer ConstByteSpan instead of the raw pointer and size.

  • Moved kanzi/core/math/rational.hpp to kanzi/core/cpp/rational.hpp.

  • Removed kzs_math. Use kanzi/core/cpp/limits.hpp, kanzi/core/cpp/math.hpp, kanzi/core/math/math_utils.hpp, kanzi/core/cpp/algorithm.hpp instead.

  • Removed kzsThread. Use std::thread instead.

  • Removed kzsThreadSleep. Use std::this_thread::sleep_for instead.

  • Removed kzsThreadLocalStorage. Use thread_local instead.

  • Removed KzcFile, KzcOutputStream, and KzcInputStream. Use ReadOnlyDiskFile, WriteOnlyDiskFile, ReadOnlyMemoryFile, MemoryParser, MemoryWriter, and file_util.hpp instead.