Kanzi 3.8 迁移指南

使用此迁移指南将 Kanzi 应用程序从 Kanzi 3.7 更新到 Kanzi 3.8。

在状态间进行动画迁移

在 State Manager 中，当您使用没有动画的过渡时，在 Kanzi 3.8 中，State Manager 发送 Transition Started 和 Transition Finished 消息。如果您的应用程序依赖于不接收这些消息，当您将应用程序升级到 Kanzi 3.8 时，请修改您的应用程序以考虑到功能的这一变化。

蒙皮网格的更改内容

如果在您的 Kanzi 应用程序中使用蒙皮网格，当将应用程序迁移到 Kanzi 3.8 时，更新网格数据和骨架节点的变换。

要仅更新 Library 中所需的项目并保留现有属性的值，请合并来自 fbx 或 dae 文件的蒙皮网格：

1. 在 Library > Resource Files > 3D Assets 中，右键单击蒙皮网格并选择 Merge 3D Asset File。请参阅 合并 3D 资产。

2. 在 Merge 工具中：

   1. 选中蒙皮网格旁边的复选框。

      这样便可以更新网格数据。

   2. 选择变换不同于现有 Kanzi Studio 项目的骨架节点。

   3. 在 Merge 工具中，点击 Resolve to source，然后点击 Merge。

   合并后，确保您对节点所做的更改，例如，在导入的 Scene 节点中添加的属性和修改的值，保持不变。

3. 在您合并的用于蒙皮网格的材质顶点着色器中，将该着色器中计算蒙皮的部分替换为在 Kanzi 3.6.8 中有效的代码，并在 Shader Source Editor 中点击 Save。

   例如，将

   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);
   

   通过

   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);
   

硬件键处理更改

要处理硬件按键输入，您必须使用按键操控器。在 Kanzi 3.8 中，Key Up 消息被替换为 Key Pressed 和 Key Released 消息。

当您在 Kanzi Studio 中打开项目时，Kanzi Studio 会自动将使用 Key Down 和 Key Up 消息的项目转换为使用 Key Pressed 和 Key Released 消息的项目，并在条件中存在键的消息节点上添加 Key Manipulator 触发器。然而，Kanzi Studio 仅自动转换在其条件中使用等号的 Key Down 和 Key Up 消息。如果在这些消息的条件中使用了除等号以外的操作，则必须手动转换所有此类键操作符。

焦点更改

Screen 节点不再是提供焦点链导航功能的焦点范围。要在您的项目中使用焦点链导航：

1. 将 Screen 节点下的第一个节点或您希望使用焦点导航的节点设置为焦点组或焦点围栏。

2. 为该节点启用 Focusable 属性。

请参阅 焦点。

字体更改

• 将 Font 类重命名为 FontRuntime，现在它还包含字体样式。因此，TextFormat、TextLayouter 和 TextShaper 现在采用 FontRuntime 而不是 Font。

• 移除了 Node::FontProperty 并用以下功能替换：

  • Node::FontFamilyProperty

  • FontStyleConcept::WeightProperty

  • FontStyleConcept::StyleProperty

• 将这些属性从 TextBlockConcept 移动并重命名到 FontStyleConcept 类：

  Kanzi 3.7	Kanzi 3.8
  TextBlockConcept::FontSizeProperty	FontStyleConcept::SizeProperty
  TextBlockConcept::CharacterSpacingProperty	FontStyleConcept::CharacterSpacingProperty
  TextBlockConcept::FixedCharacterWidthProperty	FontStyleConcept::FixedCharacterWidthProperty
  TextBlockConcept::LineSpacingProperty	FontStyleConcept::LineSpacingProperty

• 对 FontManager 类进行了以下更改：

  • 将 FontManager::createFont 替换为 FontManager::getRuntimeFont 的功能，该功能在 Kanzi 3.8 中引入。

  • 已移除 FontManager::getFontFamily。您可以从 ResourceManager 获取字体系列作为资源。

  • 已移除 FontManager::createFontFamily。请改用 FontFamily::create。

• 将这些函数从 TextFormat 和 TextLayouter 类移动到 FontStyleDefinition 类：

  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

消息更改

• 已移除 kzuMessageType。请改用 AbstractMessageTypeDescriptor。

• 删除了以 AbstractMessageType 作为参数的 MessageArguments 构造函数。要使用 AbstractMessageType 分发消息，请使用 Node::dispatchAbstractMessage()。

Prefab View 节点更改

Prefab View 节点不再重新创建节点树，如果 Prefab Template 属性（PrefabProperty）没有改变。如果您的应用程序依赖于 Kanzi 在属性写入时重新创建节点树，例如使用 On Attached 触发器，您可以通过首先将 Prefab Template 设置为空值来强制重新创建节点树。

Kanzi Engine 插件元数据更改

将 Kanzi Engine 插件元数据属性的语法从 SortingIndex 更改为 metadata.sortingIndex。请参阅 SortingIndex。

其他更改

• 将这些标头移动到新位置：

  Headers	Kanzi 3.8 位置
  模板： trigger_template.hpp	<KanziWorkspace>/Engine/include/kanzi/core.ui/template
  触发器： message_trigger.hpp on_attached_trigger.hpp on_property_changed_trigger.hpp timer_trigger.hpp	<KanziWorkspace>/Engine/include/kanzi/ui/node_component/trigger
  操作： 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_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

• 翻转了 PanManipulator::MovedMessage 增量的符号。

• 在 Mesh 和 Renderer 类中处理更改顶点或索引数据的调用现在将 ConstByteSpan 作为缓冲区，而不是原始指针和大小。

• 将 kanzi/core/math/rational.hpp 移动到 kanzi/core/cpp/rational.hpp。

• 已移除 kzs_math。请改用 kanzi/core/cpp/limits.hpp、kanzi/core/cpp/math.hpp、kanzi/core/math/math_utils.hpp、kanzi/core/cpp/algorithm.hpp。

• 已移除 kzsThread。请改用 std::thread。

• 已移除 kzsThreadSleep。请改用 std::this_thread::sleep_for。

• 已移除 kzsThreadLocalStorage。请改用 thread_local。

• 已移除 KzcFile、KzcOutputStream 和 KzcInputStream。请改用 ReadOnlyDiskFile、WriteOnlyDiskFile、ReadOnlyMemoryFile、MemoryParser、MemoryWriter 和 file_util.hpp。

另请参阅

Kanzi 3.8 发行说明

已知问题