Kanzi 3.9.1 迁移指南¶

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

颜色混合¶

Kanzi 3.9.1 修复了2D节点画笔的渲染问题，并引入了新的混合模式。请参阅混合和合成2D节点。

材料的默认混合模式从 Opaque 更改为 Alpha: Premultiplied。当您打开使用早期版本的 Kanzi Studio 创建的项目时，如果其中包含未设置混合模式的材料，Kanzi Studio 会自动为这些材料添加 Blend Mode 属性，并将其设置为 Opaque。

颜色混合改进在 Kanzi Engine API 中引入了这些差异，版本为 Kanzi 3.9.0 和 3.9.1：

Kanzi 3.9.0	Kanzi 3.9.1
`graphics_enums.hpp` `GraphicsBlendMode` 枚举值： `GraphicsBlendModeOpaque` `GraphicsBlendModeAlpha` `GraphicsBlendModeAdditive` `GraphicsBlendModePremultipliedAlpha` `GraphicsBlendModeMixedAlpha`	`graphics_blend_mode.hpp` 整数变量： `GraphicsBlendModeAdditive` `GraphicsBlendModeAlpha` `GraphicsBlendModeClear` `GraphicsBlendModeDestinationAtop` `GraphicsBlendModeDestinationIn` `GraphicsBlendModeDestinationOut` `GraphicsBlendModeDestinationOver` `GraphicsBlendModeExclusiveOr` `GraphicsBlendModeMixedAlpha` `GraphicsBlendModeMultiply` `GraphicsBlendModeOpaque` `GraphicsBlendModePremultipliedAlpha` `GraphicsBlendModeScreen` `GraphicsBlendModeSourceAtop` `GraphicsBlendModeSourceIn` `GraphicsBlendModeSourceOut`
	将 `blendMode` 参数添加到： `BrushRenderer::updateRender` `BrushRenderer::updateRenderOverride` 及其在 `ContentBrushRenderer`、`MaterialBrushRenderer`、`TextureBrushRenderer` 和 `ColorBrushRenderer` 中的实现。 `NodeCompositor2D::updateRender` `NodeVisual2D::storeRenderingParameters`
`GlRenderState::setValue(GraphicsBlendMode value)`	`GlRenderState::setBlendModeValue` `(optional<int> value)`
`BrushRenderer::RenderMode` 枚举值： `RenderModeNone` `RenderModeInvalid` `RenderModeOpaqueNoContent` `RenderModeTranslucentNoContent` `RenderModeOpaque` `RenderModeTranslucent`	`BrushRenderer::RenderMode` 枚举值： `RenderModeNone` `RenderModeContent` `RenderModeNoContent`
`BrushRenderer::updateRender()`，`BrushRenderer::updateRender(bool forceOpaque)`	`BrushRenderer::updateRender(optional<int> blendMode, bool forceOpaque, bool translucencyHint)`
`BrushRenderer::hasOpaqueRenderMode()`	已移除。
`ColorBrushRenderer` 和 `TextureBrushRenderer` 派生自 `GlBrushRenderer`。	`ColorBrushRenderer` 和 `TextureBrushRenderer` 派生自 `ContentBrushRenderer`。
`ColorBrushRenderer` 和 `TextureBrushRenderer` 方法： `getRenderOpacityValue` `getBlendModeValue` `getContentTextureValue` `getMaterial`	从基类继承的方法： `ContentBrushRenderer::getRenderOpacityValue` `BrushRenderer::getBlendModeValue` `ContentBrushRenderer::getContentTextureValue` `ContentBrushRenderer::getMaterial`
`ContentBrushRenderer::getBlendModeValue`	继承自 `BrushRenderer::getBlendModeValue`
`Brush::setOpaque`	`Brush::setContentTranslucent`
`Brush::getContentTexture`	已移除。请改用 `BrushRenderer::getContentTexture`。
`Brush::setContentTexture`	已移除。请改用 `BrushRenderer::setContentTexture`。
`NodeCompositor2D::` `isOpacityCompositionRequest`	`NodeCompositor2D::` `isOpacityAndChildrenCompositionRequest`
在： `NodeVisual2D::setForegroundBrushRenderer` `NodeVisual2D::setBackgroundBrush` `brush` 参数的数据类型是 `BrushSharedPtr`。	`brush` 参数的数据类型是 `Brush*`。
在： `GlRenderValueBinding::update` `RenderStatePropertyNotificationHandler::update`、`updateOverride` 及其实现。模板函数 `acquireRenderValueFromPropertyDefault` 和 `acquireRenderValueFromProperty` 及其相关的特化。 `object` 参数的数据类型是 `Object`。	`object` 参数的数据类型是 `PropertyObject`。
`RenderEntry3D` 构造函数正在转换。	`RenderEntry3D` 构造函数是显式的，不允许隐式类型转换。
	这些类和函数使用 `KANZI_COREUI_API`： `ColorBrushRenderer` `MaterialBrushRenderer` `TextureBrushRenderer` `acquireUniformLocation` `getUniformElementCount` `updateRenderValue` 和 `updateRenderValueOverride` 的所有特化
	`GlRenderValue` 模板类使用 `KANZI_COREUI_TEMPLATE_API`。

cubemaps¶

Kanzi 3.9.1 修复了立方体贴图图像的渲染。您不再需要翻转立方体贴图图像或修改反射即可获得预期结果。

要将您的项目迁移到 Kanzi 3.9.1，请调整 png 立方体贴图以配合修复：

当您在第三方工具中准备立方体贴图图像时，不要沿任何轴翻转图像。
使用与您用于生成 dds 立方体贴图纹理相同的立方体贴图图像。
在立方体贴图纹理中，使用 PosZ Image 属性设置立方体贴图的前面（相机后面），使用 NegZ Image 属性设置立方体贴图的背面（相机前面）。
不要修改用于采样的反射向量。使用真实世界的方向。

如果您的项目包含 png 立方体贴图，并且您在第三方图像编辑工具中手动翻转了这些立方体贴图的各个面以使其在以前版本的 Kanzi Studio 中工作，为了避免再次翻转这些面，您可以通过根据模式 <TextureName> <direction><Axis>.png 命名 png 文件来指示 Kanzi Studio 不进一步处理这些图像：

PosX Image：<TextureName> posX.png
NegX Image：<TextureName> negX.png
PosY Image：<TextureName> posY.png
NegY Image：<TextureName> negY.png
PosZ Image：<TextureName> posZ.png
NegZ Image：<TextureName> negZ.png

确保将空格字符包含在文件名中。

您从 dds 文件导入的立方体贴图纹理中的侧面图像文件已经遵循了此命名约定。

请参阅使用环境纹理贴图。

输入和焦点处理¶

使用 Kanzi Engine API 创建的 List Box 和 Scroll View 节点默认情况下不再可聚焦。要使 List Box 或 Scroll View 节点获得键盘焦点，请添加 Node::FocusableProperty 并将其设置为 true。

默认情况下，Kanzi Studio 在 List Box 和 Scroll View 节点中添加并启用 Focus > Focusable 属性。

活动和焦点¶

Activity Host 节点不再需要 Save Last Focused Node 和 Focus Scope Type 属性来启用在 Activity 节点中保存和恢复最后聚焦的节点。从此版本开始，Kanzi Studio 默认情况下不再将这些属性添加到 Activity Host 节点。

这些属性的存在不会影响应用程序的行为。但是，您可以从项目中现有的 Activity Host 节点中删除 Save Last Focused Node 和 Focus Scope Type 属性。

对 Code Behind 的更改¶

已取消为 Code Behind 设置 KANZI_HOME 环境变量的要求。

Kanzi 活动系统的更改¶

重构了这些 Kanzi 活动消息、消息参数和属性：

Kanzi 3.9.0	Kanzi 3.9.1
`ActivityConcept::PrefabAttachedMessage`	`ActivityHostConcept::ActivityPrefabAttachedMessage`
`ActivityConcept::PrefabDetachedMessage`	`ActivityHostConcept::ActivityPrefabDetachedMessage`
`ActivityConcept::StatusChangedMessageArguments::StatusArgument`	`ActivityConcept::StatusChangedMessageArguments::ActivityStatus`
`DataDrivenExclusiveActivityHostConcept::ActiveItemIndexProperty`	`DataDrivenExclusiveActivityHostConcept::ActiveActivityIndexProperty`

当您打开使用这些消息的 Kanzi Studio 项目时，Kanzi Studio 会自动应用更改。

重命名了这些 Kanzi 活动 API 和变量：

Kanzi 3.9.0	Kanzi 3.9.1
`DataDrivenExclusiveActivityHostConcept::setActivityTemplate(string prefabUrl)`	`DataDrivenExclusiveActivityHostConcept::setActivityTemplate(string_view prefabUrl)`
`DataDrivenExclusiveActivityHostConcept::s_defaultActiveItemIndex`	`DataDrivenExclusiveActivityHostConcept::s_defaultActiveActivityIndex`
`DataDrivenExclusiveActivityHostConcept::getActiveItemIndex()`	`DataDrivenExclusiveActivityHostConcept::getActiveActivityIndex()`
`DataDrivenExclusiveActivityHostConcept::setActiveItemIndex()`	`DataDrivenExclusiveActivityHostConcept::setActiveActivityIndex()`

对 Kanzi Java API 的更改¶

枚举类¶

所有 Kanzi Java API 枚举类现在实现了接口 Enum，因此提供了方法：

getValue() 获取枚举器的整数值。
toEnum() 将整数值转换为相应的枚举器。

在 Kanzi 3.9.0 中，一些枚举类通过不同名称的方法公开了这些功能，这些方法在 Kanzi 3.9.1 中被重命名。

Kanzi 3.9.0	Kanzi 3.9.1
`swigValue()`	`getValue()`
`swigToEnum()`	`toEnum()`

将 PropertyType.DataType 重命名为 PropertyDataType。属性数据类型的名称现在与本机 Kanzi Engine API 的名称匹配。

Kanzi 3.9.0	Kanzi 3.9.1
`PropertyType.DataType.Bool`	`PropertyDataType.PropertyDataTypeBool`
`PropertyType.DataType.Color`	`PropertyDataType.PropertyDataTypeColor`
`PropertyType.DataType.Float`	`PropertyDataType.PropertyDataTypeFloat`
`PropertyType.DataType.Int`	`PropertyDataType.PropertyDataTypeInt`
`PropertyType.DataType.Matrix3x3`	`PropertyDataType.PropertyDataTypeMatrix3x3`
`PropertyType.DataType.Matrix4x4`	`PropertyDataType.PropertyDataTypeMatrix4x4`
`PropertyType.DataType.Resource`	`PropertyDataType.PropertyDataTypeResource`
`PropertyType.DataType.SRT2D`	`PropertyDataType.PropertyDataTypeSRT2D`
`PropertyType.DataType.SRT3D`	`PropertyDataType.PropertyDataTypeSRT3D`
`PropertyType.DataType.String`	`PropertyDataType.PropertyDataTypeString`
`PropertyType.DataType.Vector2`	`PropertyDataType.PropertyDataTypeVector2`
`PropertyType.DataType.Vector3`	`PropertyDataType.PropertyDataTypeVector3`
`PropertyType.DataType.Vector4`	`PropertyDataType.PropertyDataTypeVector4`

Resource Manager¶

Kanzi 3.9.1 更改了自定义 Resource Manager 协议处理程序接口：

ResourceManager.LoadTask 接口现在是一个抽象类。
ResourceManager 不再是 loadFunction 和 finishFunction 的参数。请使用 ResourceManager.LoadTask.getResourceManager()。

Kanzi 3.9.0	Kanzi 3.9.1
class MyLoadTask implements ResourceManager.LoadTask { @Override public void loadFunction( ResourceManager resourceManager) { ... } @Override public void finishFunction( ResourceManager resourceManager) { ... } @Override public Resource getResult() { ... } }	class MyLoadTask extends ResourceManager.LoadTask { @Override public void loadFunction() { ... } @Override public void finishFunction() { ... } @Override public Resource getResult() { ... } }

Kanzi 3.9.0

Kanzi 3.9.1

class MyLoadTask
    implements ResourceManager.LoadTask
{
    @Override
    public void loadFunction(
        ResourceManager resourceManager)
    {
        ...
    }

    @Override
    public void finishFunction(
        ResourceManager resourceManager)
    {
        ...
    }

    @Override
    public Resource getResult()
    {
        ...
    }
}

class MyLoadTask
    extends ResourceManager.LoadTask
{
    @Override
    public void loadFunction()
    {
        ...
    }

    @Override
    public void finishFunction()
    {
        ...
    }

    @Override
    public Resource getResult()
    {
        ...
    }
}

另请参阅¶

Kanzi 3.9.1 发行说明

已知问题