Kanzi 3.9.3 迁移指南¶

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

渲染过程中的更改¶

将 CameraProperty 从 DrawObjectsRenderPass 移动到 RenderPass。

这使您能够在任何渲染通道中设置渲染通道及其子代用于渲染内容的 Camera 节点。
将 renderOverride() 的渲染过程配置文件更改为 void renderOverride(Renderer3D& renderer, CompositionStack& compositionStack, const CameraSettings* cameraSettings)。

除非 RenderPass 专门化想要更改相机设置，否则它会将指针按原样传递给子渲染通道进行渲染。该指针可以是 nullptr。

当您实现自定义渲染以修改相机设置时，通过从传递的参数复制来从堆栈构造一个本地 CameraSettings。
引入了 virtual void renderChildrenOverride(Renderer3D& renderer, CompositionStack& compositionStack, const CameraSettings* cameraSettings) 用于渲染通道。

此函数控制如何渲染渲染通道的子节点。RenderPass 的典型特化不需要重写它。

Java API 中的更改¶

当您定义消息类型时，您现在必须指定一个关联的消息参数类。因此，当您分派或处理消息时，您必须使用与消息类型关联的消息参数类。

Kanzi Studio 使用此关联为您提供可以设置或从消息参数中获取的属性列表。

消息参数类现在必须从 MessageArguments 类派生，并提供一个固定签名的构造函数：

将您的消息类型和消息参数定义从

@Metadata
public static final MessageType XMessage = new MessageType("Message.X", MessageRouting.MessageRoutingBubbling);

@Metadata
public interface XMessageArguments
{
    @Metadata
    public static PropertyType<Integer> SomeProperty = new PropertyType<>(Integer.class);
}

至 (To)

@Metadata
public static final MessageType<XMessageArguments> XMessage = new MessageType<>("Message.X", MessageRouting.MessageRoutingBubbling, XMessageArguments.class);

@Metadata
public class XMessageArguments extends MessageArguments
{
    // A constructor with a long argument that Kanzi uses to wrap native arguments.
    public XMessageArguments(long nativeObject)
    {
       super(nativeObject);
    }

    // Any additional constructors for you to use when dispatching messages.
    public XMessageArguments()
    {
       super();
    }

    @Metadata
    public static PropertyType<Integer> SomeProperty = new PropertyType<>(Integer.class);
    // Accessors for properties.
    public Integer getSomeProperty()
    {
          return getArgument(SomeProperty);
    }
    public void setSomeProperty(Integer value)
    {
          setArgument(SomeProperty, value);
    }
}

将您的消息分发调用从

MessageArguments args = new MessageArguments();
args.setArgument(XMessageArguments.SomeProperty, 1);
node.dispatchMessage(XMessageArguments, args);

至 (To)

XMessageArguments args = new XMessageArguments();
args.setSomeProperty(1);
node.dispatchMessage(XMessageArguments, args);

将您的消息处理程序从

node.addMessageHandler(XMessage, messageArguments -> {
    Integer someProperty = messageArguments.getArgument(XMessageArguments.SomeProperty);
});

至 (To)

node.addMessageHandler(XMessage, messageArguments -> {
    Integer someProperty = messageArguments.getSomeProperty();
});

您不必定义自己的消息参数类。相反，您可以在上述所有情况下使用基类 MessageArguments。此外，为属性定义访问器仅是为了方便。您仍然可以使用通用参数设置器和设置器。

请参阅使用消息和创建自定义类型。

Metaclass 接口 iteratePropertyTypes() 和 iterateMessageTypes() 现在分别返回 AbstractPropertyType 和 AbstractMessageType 的可迭代对象。
将这些 Node 接口上的资源 ID 参数类型从 String 更改为 ResourceID：
- addResource
- removeResource
- containsResource
- findResourceUrl
- acquireResource
- tryAcquireResource
- acquireResourcesAsync
更改自：
```
node.acquireResource("resource id");
```
到:
```
node.acquireResource(new ResourceID("resource id"));
```

对 Android 应用程序模板的更改¶

Android 应用程序模板现在支持从 Kanzi Studio 添加 Java Code Behind。要在 Kanzi Studio 中使用 Code Behind 功能，您必须迁移基于旧模板的现有应用程序。

Kanzi Studio 中的一个已知问题要求使用 Java Code Behind 功能的 Android 应用程序包必须保持为 com.example.<ProjectName>。

要将您的 Kanzi 应用程序迁移以使用更新的模板：

在 Kanzi Studio 中，打开您的项目。在主菜单中，选择 Project > Properties，并在 Properties 中将 Java Project 属性设置为启用。
保存项目并重启 Kanzi Studio。

在您的应用程序包目录中，创建 KanziGenerated.java 文件，并在该文件中添加以下代码。

例如，在 <ProjectName>/Application/configs/platforms/android_gradle/app/src/main/java/com/example/<ProjectName> 目录中创建此文件。

// GENERATED FILE. DO NOT EDIT.

package com.example.<ProjectName>;

import com.rightware.kanzi.Domain;

// [Plugin imports]

public class KanziGenerated {

static void registerPlugins(Domain domain) {

// [Plugin registrations]
}

}

在初始化您的活动或附加您的 Kanzi 视图期间，调用 KanziGenerated.registerPlugins(domain)。

要了解有关 KanziGenerated.java 的更多信息，请参阅使用 Kanzi Studio 生成的插件。

类元数据中的更改¶

将 PropertyTargetEasingInterpolator 元类重命名为 Kanzi.PropertyTargetEasingInterpolator。
将 PropertyTargetEasingInterpolator.SetEnabledMessageArguments MessageArgument 元类重命名为 Kanzi.PropertyTargetEasingInterpolator.SetEnabledMessageArguments。

重命名了这些 StateManager MessageArgument 元类：

Kanzi 3.9.2	Kanzi 3.9.3
`Message.StateManagerMessageArguments`	`Kanzi.StateManager.StateManagerMessageArguments`
`Message.StateManagerStateChangeMessageArguments`	`Kanzi.StateManager.StateChangeMessageArguments`
`Message.StateManagerGoToStateMessageArguments`	`Kanzi.StateManager.GoToStateMessageArguments`
`Message.StateManagerGoToDefinedStateMessageArguments`	`Kanzi.StateManager.GoToDefinedStateMessageArguments`
`Message.StateManagerGoToNextDefinedStateMessageArguments`	`Kanzi.StateManager.GoToNextDefinedStateMessageArguments`
`Message.StateManagerGoToPreviousDefinedStateMessageArguments`	`Kanzi.StateManager.GoToPreviousDefinedStateMessageArguments`
`Message.StateManagerEnteredStateMessageArguments`	`Kanzi.StateManager.EnteredStateMessageArguments`
`Message.StateManagerLeftStateMessageArguments`	`Kanzi.StateManager.LeftStateMessageArguments`
`Message.StateManagerTransitionMessageArguments`	`Kanzi.StateManager.TransitionMessageArguments`
`Message.StateManagerTransitionStartedMessageArguments`	`Kanzi.StateManager.TransitionStartedMessageArguments`
`Message.StateManagerTransitionFinishedMessageArguments`	`Kanzi.StateManager.TransitionFinishedMessageArguments`

重命名了这些 ValueAccumulator MessageArgument 元类：

Kanzi 3.9.2	Kanzi 3.9.3
`FloatValueAccumulator.SetAccumulatedValueBoundariesMessageArguments`	`Kanzi.FloatValueAccumulator.SetAccumulatedValueBoundariesMessageArguments`
`IntValueAccumulator.SetAccumulatedValueBoundariesMessageArguments`	`Kanzi.IntValueAccumulator.SetAccumulatedValueBoundariesMessageArguments`
`ValueAccumulator.StartMessageArguments`	`Kanzi.ValueAccumulator.StartMessageArguments`
`ValueAccumulator.StopMessageArguments`	`Kanzi.ValueAccumulator.StopMessageArguments`
`ValueAccumulator.PauseMessageArguments`	`Kanzi.ValueAccumulator.PauseMessageArguments`
`ValueAccumulator.ResumeMessageArguments`	`Kanzi.ValueAccumulator.ResumeMessageArguments`

蒙皮网格的更改¶

为了使多个节点能够使用相同的蒙皮网格，Kanzi 现在将蒙皮网格的运行时数据存储在 Model3D 中，而不是 Mesh。为实现这一点，对 Mesh API 进行了以下更改：

移除了这些蒙皮网格访问器：
- Mesh::getBoneCount() > size_t
- Mesh::getBoneNode(size_t) > Node3D*
- Mesh::getBoneChildJoint(size_t) > Node3D*
添加了这些蒙皮网格访问器：
- Mesh::getSkeleton > Mesh::Skeleton
- Model3D::getSkeletonRuntime > Mesh::Skeleton

更改了这些函数签名：

Kanzi 3.9.2	Kanzi 3.9.3
`Mesh::updateBoundingBox(Node3D*)`	`Mesh::updateSkeletonTransformation(Model3D&)`
`Mesh::attach(Node*)`	`Mesh::attachSkeleton(Model3D*)`
`Mesh::detach(Node*)`	`Mesh::detachSkeleton(Model3D*)`

网格数据访问的更改¶

Kanzi 现在支持网格中的32位索引。该改进在 Mesh API 中引入了这些更改：

更改了这些函数签名：

Kanzi 3.9.2	Kanzi 3.9.3
`void* Mesh::getVertexData(size_t)`	`span<const byte> Mesh::getVertexData(size_t)`
`uint16_t* Mesh::getClusterIndexData(size_t)`	`span<const byte> Mesh::getClusterIndexData(size_t)`

添加了 Mesh::getClusterIndexType() 用于检查网格簇的索引类型。

对变形着色器的更改¶

变形着色器现在计算基础变形的权重。要将此更改应用于使用旧变形着色器的项目：

在 Library > Materials and Textures > Material Types 中删除您要更新的变形材质类型。

例如，如果您使用 VertexPhongMorph 材质类型，请删除该材质类型。
在 Library > Materials and Textures 按 Alt 并右键单击 Material Types 中导入您要使用的变形材质类型。

例如，导入 VertexPhongMorph 材质类型。
在 Library > Materials and Textures > Materials 中，选择您与旧变形着色器材质类型一起使用的材质，并在 Properties 中将 Material Type 属性设置为您在上一步中导入的变形材质。
在 Library > Materials and Textures > Materials 中，删除 Kanzi Studio 在导入材质类型时自动创建的变形材质。