Kanzi 3.6 迁移指南¶

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

头文件的目录结构¶

Kanzi 3.6 引入了 <KanziWorkspace>/Engine 目录结构的更改。要将您的 Kanzi 应用程序从 Kanzi 3.5 迁移到 Kanzi 3.6，请更新应用程序代码中的包含路径。

例如，如果您的应用程序使用 kzs_file_base.h、v8_module.hpp 和 gl_graphics_output.hpp 头文件，请更改

#include <system/file/kzs_file_base.h>
#include <kanzi/v8_module.hpp>
#include <kanzi/graphics_backend/gl_graphics_output.hpp>

至 (To)

#include <kanzi/core/legacy/file/kzs_file_base.hpp>
#include <kanzi/js/module.hpp>
#include <kanzi/core.ui/platform/graphics_backend/gl/gl_graphics_output.hpp>

这些表格显示了 Kanzi 3.5 和 3.6 之间目录结构的差异。

Kanzi 3.5	描述 (Description)
`Engine/include/application_framework`	包含平台特定的应用程序头文件。
`Engine/include/core`	包含实用程序、内存管理和数据结构头文件。
`Engine/include/kanzi_components`	包含 Kanzi UI 组件头文件。
`Engine/include/kanzi_v8`	包含 JavaScript 支持的头文件。
`Engine/include/system`	包含本地平台抽象和图形系统初始化头文件。
`Engine/include/user`	包含应用程序逻辑和子系统头文件。

Kanzi 3.6	描述 (Description)
`Engine/include/kanzi/core`	合并以下 Kanzi 3.5 目录的非图形部分的内容： `include/core` `Engine/include/system` `Engine/include/user`
`Engine/include/kanzi/core/legacy`	包含这些 Kanzi 3.5 目录的内容，并将在即将发布的 Kanzi 版本中被移除： `Engine/include/system` `Engine/include/core`
`Engine/include/kanzi/core.ui`	包含构成所有UI控件和UI组件基础的UI功能的基本子系统。例如，这包括输入、渲染和布局功能。结合这些 Kanzi 3.5 目录的图形部分内容： `include/core` `Engine/include/system` `Engine/include/user`
`Engine/include/kanzi/js`	包含 JavaScript 支持的头文件。替换 Kanzi 3.5 目录 `Engine/include/kanzi_v8`。
`Engine/include/kanzi/ui`	包含 Kanzi UI 组件的头文件。替换 Kanzi 3.5 目录 `Engine/include/kanzi_components`。

预处理器定义 (Preprocessor Defines)¶

如果您创建了自己的 makefile 或构建脚本来构建您的 Kanzi 应用程序，要使用 Kanzi 3.6 构建 Kanzi 应用程序，请更新这些文件以包含 KANZI_FEATURE_3D 预处理器定义。

日志¶

Kanzi 3.6 引入了日志系统的更改。日志系统具有新的类型安全格式语法，并引入了日志级别和日志类别以实现消息分类和过滤。日志类别允许您为每个类别过滤消息，并在编译时过滤消息。

日志头文件现在位于目录 Engine/include/kanzi/core/log 中。要将消息写入日志，请使用日志宏，并为日志消息设置日志级别和类别。在 Kanzi 3.6 中，您不能再将日志消息打印到应用程序窗口，而只能打印到调试控制台，并且应用程序配置函数 logVisualizationEnabled() 不再可用。

本示例显示通用日志功能从 Kanzi 3.5 迁移到 Kanzi 3.6。

// Define a new log category in a header file.
// For example, to define a log category called Texture.
#define TEXTURE_LOG_CATEGORY KZ_LOG_CREATE_CATEGORY(KZ_LOG_ENABLED_CATEGORY, "Texture")

// Error log.
// In Kanzi 3.5
// kzsLog(KZS_LOG_LEVEL_INFO, "Texture loaded.");
// In Kanzi 3.6
kzLogInfo(TEXTURE_LOG_CATEGORY, ("Texture loaded."));

// Formatted text.
// In Kanzi 3.5
// kzsLogFormat(KZS_LOG_LEVEL_INFO, ("Texture size %4dx%4d", 400, 600));
// In Kanzi 3.6
kzLogInfo(TEXTURE_LOG_CATEGORY, ("Texture size {:4}x{:4}.", 400, 600));

// Assign test log message to the Generic log category.
// In Kanzi 3.5
// kzsLog(KZS_LOG_LEVEL_WARNING, "Test warning message.");
// In Kanzi 3.6
kzLogWarning(KZ_LOG_CATEGORY_GENERIC, ("Test warning message."));

// In Kanzi 3.6 the type of the argument is deduced at compile-time so that you do not have to set it.
// In Kanzi 3.5
// kzsLogFormat(KZS_LOG_LEVEL_INFO, ("Test different formatting: %+04d %#x %12.15f %-+12.15g", 1, 2, 0.1, 0.5));
// In Kanzi 3.6
kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Test different formatting: {:+04} {:#x} {:12.15} {:<+12.15} ", 1, 2, 0.1, 0.5));

请参阅 log.hpp。

渲染 (Rendering)¶

Kanzi 3.6 引入了渲染的更改：

RenderPass 类的类层次结构已更改：
- 在 Kanzi 3.6 LegacyRenderPass 中调用了 Kanzi 3.5 RenderPass 类。
- Kanzi 3.5 Composer 类在 Kanzi 3.6 RenderPass 中被调用。如果您定义自己的渲染通道，必须从 RenderPass 类派生。
如果您创建自己的渲染通道，RenderPass::renderOverride() 函数替换了 Kanzi 3.5 虚函数 applyOverride()。

Kanzi Engine 插件¶

定义属性类型¶

在 Kanzi 3.6 中，用于定义 Kanzi Engine 插件中属性类型的标志已重命名。

Kanzi 3.5	Kanzi 3.6
`KZU_PROPERTY_TYPE_CHANGE_FLAG_FINAL_TRANSFORMATION`	`PropertyTypeChangeFlagFinalTransformation`
`KZU_PROPERTY_TYPE_CHANGE_FLAG_MEASURE`	`PropertyTypeChangeFlagMeasure`
`KZU_PROPERTY_TYPE_CHANGE_FLAG_PARENT_MEASURE`	`PropertyTypeChangeFlagParentMeasure`
`KZU_PROPERTY_TYPE_CHANGE_FLAG_ARRANGE`	`PropertyTypeChangeFlagArrange`
`KZU_PROPERTY_TYPE_CHANGE_FLAG_RENDER`	`PropertyTypeChangeFlagRender`
`KZU_PROPERTY_TYPE_CHANGE_FLAG_DRAW`	`PropertyTypeChangeFlagDraw`
`KZU_PROPERTY_TYPE_CHANGE_FLAG_CONSTRAINT`	`PropertyTypeChangeFlagConstraint`

编辑器元数据¶

Kanzi 3.6 引入了更改，影响您在 Kanzi Engine 插件中为您创建的组件声明编辑器元数据的方式。

例如：在 Kanzi 3.5 中，要为自定义节点 VideoView2D 创建自定义属性类型 VideoFileNameProperty，您使用了

PropertyType<string> VideoView2D::VideoFileNameProperty(KZ_PROPERTY_TYPE_EDITOR_INFO([]() -> kanzi::PropertyTypeEditorInfo::AttributeDictionary { kanzi::PropertyTypeEditorInfo::AttributeDictionary dict;
    dict["DisplayName"] = "Video Filename";
    dict["Tooltip"] = "Video file to be played";
    dict["Host"] = "VideoView2D:freq";
    return dict; }()), kzMakeFixedString("VideoView2D.VideoFileName"), "", 0, false);

在 Kanzi 3.6 中，要创建相同的自定义属性类型，使用

PropertyType<string> VideoView2D::VideoFileNameProperty(kzMakeFixedString("VideoView2D.VideoFileName"), "", 0, false,
                                                        KZ_DECLARE_EDITOR_METADATA
                                                        (
                                                            metadata.displayName = "Video Filename";
                                                            metadata.tooltip = "Video file to be played";
                                                            metadata.host = "VideoView2D:freq";
                                                        ));

本表显示了在 Kanzi 3.5 和 3.6 之间声明 Kanzi Engine 插件编辑器元数据的差异。

Kanzi 3.5	Kanzi 3.6
`dict["Category"]`	`metadata.category`
`dict["DefaultValue"]`	`metadata["DefaultValue"]`
`dict["DisplayName"]`	`metadata.displayName`
`dict["Editor"]`	`metadata.editor`
`dict["Host"]`	`metadata.host`
`dict["LowerBound"]`	`metadata["LowerBound"]`
`dict["Step"]`	`metadata["Step"]`
`dict["UpperBound"]`	`metadata["UpperBound"]`
`dict["Tooltip"]`	`metadata.tooltip`
`dict["Type"] = "Enum";dict["Options"] = "string1\|int1;string2\|int2;...;stringN\|intN";`	`metadata.valueProvider = "Enum:string1\|int1;string2\|int2;...;stringN\|intN";`
`dict["Type"] = "ProjectObject";dict["TargetType"] = "value";`	`metadata.valueProvider = "ProjectObject:value";`
`dict["Type"] = "PropertyType";`	`metadata.valueProvider = "PropertyType";`
`dict["Type"] = "StringList";`	`metadata.valueProvider = "StringList";`

Kanzi 3.5 中所有未在此列出的字段均取自属性类型本身的元数据标准字段。

请参阅扩展 Kanzi Engine 的功能和在 Kanzi Studio 中显示 Kanzi Engine 插件自定义类型的参考。。

触发器和动作¶

在 Kanzi 3.6 中，触发器在 Trigger 类中定义，动画播放器在 AnimationPlayer 类中定义。两个类都派生自 NodeComponent 类。在 Kanzi 3.5 中，AnimationPlayer 类派生自 Trigger 类。

Preload Resources 操作和 On Preloading of Resources Completed 触发器¶

Preload Resources 操作和 On Preloading of Resources Completed 触发器不再可用。使用 Prefab View 节点在运行时异步加载资源。请参阅使用节点预设。

要在应用程序运行时使用 Kanzi Engine API 异步加载资源，请使用 ResourceManager::acquireResourcesAsync 和 Node::acquireResourceAsync。在 Kanzi Engine API 中，请参阅 collect_resource_urls.hpp 文件。

当您打开使用早期版本的 Kanzi Studio 创建的项目，其中包含 Preload Resources 操作或 On Preloading of Resources Completed 触发器时，Kanzi Studio 3.6 会删除这些操作和触发器。

Play Animation 操作¶

Play Animation 操作不再可用。请改用动画播放器和操作。请参阅 Kanzi 3.5 迁移指南。

属性命名空间¶

在 Kanzi Studio 3.6 文件夹中，Library > Property Types 显示了属性类型命名空间层次结构。

当您打开使用早期版本的 Kanzi Studio 创建的项目，其中包含 Library > Property Types 中的文件夹时，Kanzi Studio 3.6 会删除这些文件夹，并将属性类型放置在 Library > Property Types 根目录中。

编辑网格的特性¶

当您打开您的 Kanzi Studio 项目时，Kanzi Studio 会修改项目中包含的网格的数据：

Kanzi Studio 将 Kanzi Studio 3.5 网格属性映射转换为 Kanzi Studio 3.6 使用的样式。3.5 样式映射具有网格和着色器属性名称对。除此之外，3.6 样式还包括语义和语义索引字段。转换器尝试将网格属性映射到与语义和语义索引字段匹配的着色器属性。Kanzi Studio 将其在此转换过程中遇到的警告写入 KanziStudio.log。
网格属性现在包含导出语义和导出语义索引。如果在此转换期间未设置导出属性，Kanzi Studio 将从导入语义中复制导出语义并安排语义索引。

要查看 Kanzi Studio 对网格属性映射所做的完整修改列表，请在打开早期版本的 Kanzi Studio 创建的项目后，打开 Kanzi Studio 日志文件。您可以在 %USERPROFILE%\AppData\Local\Temp\KanziStudioLogs\KanziStudio.log 中找到 Kanzi Studio 日志。请参阅

您现在可以使用 Mesh Attributes Editor 编辑网格的属性。Mesh Attributes Editor 替换了早期版本 Kanzi 中使用的映射网格属性。请参阅优化网格。

../../_images/mesh-attributes-editor.png

应用程序空闲状态¶

Kanzi 现在可以检测到没有更改时停止渲染。如果在您的 Kanzi 应用程序中，您在着色器中使用了通过 Kanzi Engine API 声明的自定义属性类型，或者在 Kanzi Studio 中创建了它们，确保将这些属性类型的 Affect Rendering 属性启用。请参阅应用程序空闲状态。

API 重命名¶

getProperty 函数已从

bool getProperty(PropertyType propertyType, DataType& value)

至 (To)

optional<DataType> getOptionalProperty(PropertyType propertyType)

setTrajectoryResourceID 函数已从

setTrajectoryResourceID(ResourceID("MyTrajectory"));

至 (To)

setTrajectory(trajectory);

移除了 TrajectoryListBox3D::setLoopAlongY 并将 TrajectoryListBox3D::setLoopAlongX 更改为来自 TrajectoryListBox3D::setLooping。
将 KzcVolume 转换为 C++ 并重命名为 Box。
类 Shader 重命名为 ShaderProgram。
VertexAttribute 类分为 MeshVertexAttribute 和 ShaderVertexAttribute 类，这两个类都派生自 VertexAttribute 基类。
更改了 Texture::CreateInfo。
Texture::calculateMipmapLevelCount 更改为 calculateMipmapLevelCount。
枚举 Usage 从 Surface 移动到了 Framebuffer 类。
为属性通知处理程序更改了回调签名：
- 将第一个参数从 Object 更改为 PropertyObject。
- DataType 指定您订阅的属性的数据类型。例如，使用 int、float 或任何其他支持的数据类型。
- 将 KzuPropertyNotificationReason 更改为 PropertyNotificationReason。
```
Callback(PropertyObject& object, DataType& data, PropertyNotificationReason reason, void* userData)
```

另请参阅¶

Kanzi 3.6 发行说明

已知问题