Kanzi 4.0.0 版本说明

本说明列出了 Kanzi 4.0.0 alpha 和 beta 版本中的所有功能、更改和重要修复。

Kzm 文件格式

在 Kanzi Studio 中引入了 kzm 文件格式，以替代 kzproj 文件格式。使用 kzm 文件格式时，Kanzi Studio 会将工程存储在多个 kzm 文件中，而不是单个工程文件中。

kzm 文件格式旨在通过以下方式改进 Kanzi Studio 工程的更改审查、团队合作与协作：

• 提供细粒度、人类可读的文件，让您可以清楚地查看和审查具体更改了哪些内容

• 减少合并冲突，并使剩余的冲突更易于解决

• 简化在不同工程之间共享工程项的操作

• 通过便于比较差异的文件实现可脚本化的修改

Kanzi Studio 现在以 kzm 文件格式保存所有新工程。请参阅 Kzm 文件格式。

Kanzi Studio 仍可打开 kzproj 工程，但当您保存此类工程时，Kanzi Studio 会自动将其转换为 kzm 并移除 kzproj 文件。此转换不可逆。以 kzm 格式保存工程后，您将无法再将该工程恢复为 kzproj 格式。

在完成保存操作之前，Kanzi Studio 会显示一条通知，告知您此转换。

Kanzi graphics

引入了 Kanzi graphics (kzgfx)，即 Kanzi 的渲染硬件接口 (RHI)。Kanzi graphics 支持在 OpenGL 3.3+、OpenGL ES 3.0+ 或 Vulkan 1.1+ 上运行的 Kanzi 应用程序。请参阅 Kanzi graphics。有关如何选择要使用的 API 的信息，请参阅 图形库。

在 Project > Properties 中，使用 Preview Graphics API Configuration 属性设置 Kanzi Studio Preview 使用哪个 API。例如，要使用 OpenGL 渲染器，请将该属性设置为 OpenGL。

在应用程序配置中，您可以：

• 设置与 Kanzi Vulkan 后端一起使用的首选 GPU 类型。请参阅 首选 Vulkan GPU。

• 为 Kanzi 图形库启用统计和验证层。使用这些信息检查您的应用程序是否正确使用图形 API。请参阅 GraphicsStatisticEnabled 和 GraphicsValidationEnabled。

• 支持的 ASTC 图形格式已扩展为包括 HDR 格式，这些格式在 Kanzi Studio 中作为纹理格式提供。请参阅 使用 ASTC 算法

要迁移您的 Kanzi 应用程序，请参阅 引入 Kanzi Graphics。

Prism 图编辑器

引入了 Prism 图编辑器，这是一种用于创建渲染图的可视化节点工具。您可以添加或移除渲染节点，并快速迭代视觉效果。图清晰地概述了渲染操作，让您可以调整属性，并即时显示结果。请参阅 Prism 图。

Android

• 更新了所有 Android 应用程序模板，以使用最新的 Gradle 8+ 工具。这些模板现在支持 Android Studio Ladybug 和 JDK 21。

• 重构了 Kanzi 与 Gradle 的集成，用一个透明、可修改且可复制的子工程替代了 Kanzi Gradle 插件。这意味着您可以通过将该子工程复制到您的 Android 应用程序中，将 Kanzi 引入您的 Android 应用程序。请参阅 将 Kanzi Android framework (droidfw) 添加到 Android 应用程序。

• 引入了 Android library 模板。使用此模板，您可以导出包含预构建 Kanzi C++ 库的 AAR。您可以在任意数量的 Android 应用程序中使用它。这意味着，只要您的应用程序工程可以从您的包管理系统或版本控制中获取预构建的 Kanzi AAR，您的应用程序构建就无需访问 Kanzi 安装。

  要了解有关此工作流程的更多信息，请参阅 将 Kanzi 作为预构建库 (AAR) 集成。

• 将 Android NDK 版本更新为 26.3.11579264。请参阅 对 Android NDK 版本的更改。

• 更新了 Android 应用程序模板和示例，以显式设置 CMake 版本。

• 将 Kanzi application framework (appfw) 和 Kanzi Android framework (droidfw) 的 Java 语言版本升级到 11。

后备字体支持

Kanzi 现在允许您为字体系列定义后备字体链。如果主字体中缺少某个字形，Kanzi 将使用列表中的下一个字体来渲染该字形。请参阅 字体后备

彩色字体

Kanzi 现在可以使用包含表情符号和其他彩色字形的字体来渲染文本。请参阅 彩色字体。

文本布局优化

• Kanzi 现在会缓存已整形的文本。在不同约束条件下渲染相同文本时，这可提高布局性能。

• 渲染文本时，对于位于内边距区域内但超出文本布局区域的文本，Kanzi 不再进行裁剪。

资源 (Resources)

新增了 Asset Toolkit，其中包含易于使用的现成组件和材质，它们具有相似的结构和属性集，可帮助您更快地创建 Kanzi 应用程序。请参阅 Asset Toolkit。

Kanzi Studio 预览

• 在 Kanzi Studio 中，您现在可以使用 Screenshot 按钮 直接在 Preview 窗口中截图。请参阅 为 Preview 截图。

  

• 在 Kanzi Studio 中，调试对象 (Debug Objects) 的可视化效果已更新。

  

• 在 Kanzi Studio 中，调试网格 (Debug Grid) 的可视化效果已更新。

  

• 现在，您可以在 User Preferences > Experimental 选项卡中启用实验性选择轮廓

  

Kanzi Studio 可用性

• 在 Kanzi Studio 中改进了工具提示：

  • 您现在可以从工具提示中访问功能和 Kanzi Engine C++ API 参考文档。

    

  • 工具提示现在显示默认和自定义 Kanzi Studio 快捷键。有关默认快捷键列表以及如何设置自定义快捷键，请参阅 Default shortcut keys。

    

  • 您现在可以在工具提示中复制 Kanzi Engine 属性类型名称。

    

  • Kanzi Studio 现在会在下拉菜单中显示属性类型的工具提示。

    

• 现在，您可以在可停靠的 Related Items 窗口中查看与所选项相关的节点和资源。该窗口提供了直接导航至相关项的功能。

  从任意节点或资源的上下文菜单中，或从 Window 主菜单中打开该窗口。

  

• 在 Node Tree 中，当状态机、绑定、数据源绑定或动画设置了某个节点中部分属性的值时，该节点旁边现在会显示一个指示灯。

  

• 现在，您可以在 Library 窗口中搜索和过滤项。

  

• 现在，您可以同时在多个节点中添加、编辑和删除相同的绑定。

• 现在，您可以直接从属性开始创建绑定，并可从该属性的上下文菜单中查看影响该属性的所有绑定。

  请参阅 创建简单绑定。

  

• Kanzi Studio 现在提供了重新设计的 New Project 窗口，可简化新工程的创建。请参阅 创建工程。

  

• 当您重命名工程时，Kanzi Studio 现在会在保存工程时更新主工程文件的名称。

• Kanzi Studio 锁定文件现在使用固定名称 KanziStudio.lock。

• 将 SaveProject 和 NewProject 命令更改为接受目录路径，而不是工程文件路径。要迁移 Kanzi Studio 脚本，请参见 对 Kanzi Studio 命令的更改。

• Kanzi Studio 现在要求 Scene 节点必须始终是 Viewport2D 节点中的第一个子节点。这样可以正确处理焦点并提高应用程序性能。此更改不需要您迁移工程，但 Kanzi Studio 会突出显示不符合这些要求的 Scene 节点。

• 从 Kanzi Studio 构建 Android 包时，Kanzi Studio 现在会根据工程的 Binary File Name 属性导出 cfg 文件。有关迁移说明，请参见 Kanzi Studio Android 包导出的更改。

• 您现在可以从所有预设件的根节点访问屏幕节点的资源字典。这使您可以在节点预设件内的绑定中引用和使用屏幕节点字典中定义的别名。

• 在 Animation Clip Editor 中，使用 Keyframe tool 时，Kanzi Studio 现在会自动选择最后创建的关键帧。这样您就可以直接编辑该关键帧的值，而无需先切换到 Move tool 并选择该关键帧。

• 在 Prefabs 窗口中，省略号按钮会打开一个附加菜单，您可以通过该菜单删除未引用项、折叠或展开树。

• 在 Animation Clip Editor 中，使用 Move tool 选择节点或曲线时，如果存在多个控制点，Kanzi Studio 现在会选择离光标最近的控制点。

• 在 State Manager 中，当您尝试设置 Mesh Material 属性状态时，Kanzi Studio 现在会发出警告并提供变通方法说明。

• 在 Asset Packages 中，当您导入相同的资产包时，Kanzi Studio 现在会复制其预设件并递增其名称中的编号，而不是替换现有的资产包。

• 在 Kanzi Studio 中，按住 Ctrl 键点击展开器时，现在会展开和折叠其下的所有树项。

• 您现在可以在 Kanzi Studio 中登录您的 Kanzi Account。请参阅 Kanzi Hub 和 Kanzi Account。

  

• 在 Kanzi Studio 的 Node Tree 中，您现在可以在 Kanzi Studio 工程中右键点击覆盖指示灯，然后在上下文菜单中选择要导航至的源。

  

• Kanzi 安装程序现在会添加一个将 .kzm 文件关联到 Kanzi Studio 的注册表条目。

• Kanzi 安装程序现在会添加一个注册表条目，用于为 Windows 和 Git 启用长文件路径支持，这是 .kzm Kanzi Studio 工程文件格式所必需的。

• 在 Project Merge 中，当您选择仅存在于源工程中的项时，Kanzi Studio 现在会显示该项的属性。

• 您不能再在根目录中，或在现有工程的子目录或父目录中创建工程。

• Kanzi Studio 在加载工程期间不再更新网格数据版本。

• 创建新的 Animation 时，Kanzi Studio 现在会自动添加两个默认关键帧。

• 现在，您可以从 Kanzi Engine 插件在选择器中访问计算材质。在元数据中，使用 MaterialComboBox.ComputeMaterialSelector 编辑器。请参阅 Kanzi Studio 属性编辑器用于在 Kanzi Engine 插件中声明的属性类型。。

文档 (Documentation)

• 通过 Documentation AI 工具获取有关 Kanzi 的解答。在 Documentation 中：

  • 点击 Ask AI，开始与 Kanzi AI 助手对话

  • 使用 AI 助手工具为您的 AI 工具设置 Kanzi 上下文。例如，通过 Claude Desktop 或 Visual Studio Code 连接到 Documentation MCP 服务器。

  

• Kanzi 示例和教程工程不再包含在 Kanzi 安装程序中。您可以在 Kanzi Studio 的 Quick Start 窗口的相应部分中下载教程和示例工程。

  

• 所有示例、教程和资源工程现已迁移到 kzm 文件格式。

• Node2D_plugin 示例现在无需修改代码即可用于任何 Kanzi 工程。

• Android data source 示例现在与教程代码一致。

平台

• Kanzi Engine 现在会在 QNX 上报告鼠标滚轮事件。

• 您现在可以以逗号分隔的格式列出 EGL 特性。请参阅 listEGLAttributes。

• 您现在可以将 EGL 错误代码转换为字符串。请参阅 Kanzi Engine C++ API 参考 中的 kzsEGLErrorString。

• 将 QNX EGL 图形输出 API 从 C 转换为 C++。

  在 Kanzi Engine C++ API 参考中，请参阅 qnx::DefaultQnxEGLGraphicsOutput。

• 您现在可以为您的应用程序设置窗口类名。请参阅 WindowClassName。

• 您现在可以在 Kanzi Engine C++ API 中为 Wayland XDG shell 设置应用程序 ID。请参阅 kanzi::wayland::XDGToplevel::setId 和 kanzi::wayland::XDGShell::setAppId。

• 在 Wayland 平台包中添加了 wayland::WaylandIVIEGLGraphicsOutput，作为一种图形输出选项。

• 在 QNX 上，您现在可以设置希望 Kanzi 应用程序使用的上下文类型标志。请参阅 QNX 上下文类型选择。

• qnx::DefaultQnxEGLGraphicsOutput 现在支持 QnxWindowBufferCount 配置选项，该选项用于设置要使用的窗口缓冲区数量。为确保兼容性，如果您未显式设置此配置选项，Kanzi 将使用 WindowBufferCount 配置选项中的值。请参阅 QnxWindowBufferCount 和 WindowBufferCount。

• qnx::DefaultQnxEGLGraphicsOutput 现在遵循：

  • 默认窗口位置和大小设置

  • 默认窗口 z 顺序设置

  • 窗口组名称

  • 默认显示器索引

  • 表面填充位设置

• Kanzi 不再支持 QNX 开发平台 7.0.0。

• POSIX 系统上的事件文件描述符值不再受 FD_SETSIZE 限制。

• 更改了与 XDG 和 IVI 相关的 Wayland 类名，使其遵循驼峰式命名法 (CamelCase)。例如，XDGToplevel 已更改为 XdgToplevel。

• 所有平台现在默认使用 Kanzi 图形。要迁移您的 Kanzi 应用程序，请参阅 引入 Kanzi Graphics。

• 以下后端现在可以正确设置 EGL 窗口表面的颜色空间特性：

  • Android WS

  • Emscripten

  • QNX/PBuffer

  • X11/EGL

• 添加了一个配置选项，用于为平台层启用额外的调试日志。请参阅 PlatformLoggingEnabled。

• 在 Linux DRM/GBM 平台上，DeviceIdentifier 设置现在优先于 DRM 模块识别。以前，仅当所有 DRM 模块都无法打开时才会使用 DeviceIdentifier。

• 对于不支持浮点数 from_chars() 的旧版工具链，Kanzi 现在提供了其自己的实现。

• Wayland IVI 后端上的表面不透明度设置现在解释为浮点数，而不是整数。请参阅 wayland::IviSurfaceProps::opacity 和 wayland::IviLayerProps::opacity。

• 在 QNX 上，您现在可以为 Kanzi 应用程序窗口启用 QNX Screen 属性的自布局模式。请参阅 QnxWindowSelfLayout。

• 将所有依赖于平台的窗口和输入代码移至单独的库 (kzplatform) 中。kzplatform 的整个对外 API 均视为实验性 API，在将来的版本中可能会发生更改。系统库现在链接到 kzplatform，而不是 kzcoreui。

Kanzi Engine C++ API

• 添加了以下用于处理 span 的辅助方法：

  • as_bytes 将 span 转换为字节 span。

  • fromBytes 将字节 span 转换为类型化对象的 span。

  • toSpan 将容器转换为覆盖该容器的 span。

  • asSpan 和 asConstSpan 将单个元素转换为覆盖该单个元素的 span。

• 添加了 to_underlying，用于将枚举转换为其底层类型。

• 添加了 readAsBytes，用于将文件内容加载到字节向量中。

• 添加了 containsFlag 和 containsAnyFlag，用于测试位域枚举是否包含特定标志。

• 添加了 VectorMap，用于在向量中存储少量键值对。

• 从 PinchManipulator 中移除了不起作用的 setScaleRecognitionThreshold 和 setRotationRecognitionThreshold 函数。

  请参阅 捏合操纵器的更改。

• 在 Renderer 类中，将 setActiveGLGraphicsOutput 方法重命名为 Renderer::setActiveGraphicsOutput。请参阅 Renderer API 的更改。

• 从所有同时以 Renderer 或 kanzi::Renderer3D 为参数的方法中移除了 CompositionStack 参数。您现在可以通过 Renderer::getCompositionStack 访问 CompositionStack 实例。请参阅 对合成堆栈的更改。

• 修改了 CompositionStack，使 CompositionStack::pushComposition 使用 Framebuffer 类，而不是 NativeFramebufferHandle。请参阅 对合成堆栈的更改。

• 移除了 GlRenderValue 和 GlBlendModeRenderValue 类以及 updateRenderValue 函数。请参阅 Renderer API 的更改。

• 从 GraphicsPrimitiveType 枚举中移除了 GraphicsPrimitiveTypeLineLoop 选项。请参阅 Renderer API 的更改。

• 简化了 Renderer 类中与帧缓冲区相关的方法。请参阅 Renderer API 的更改。

• 移除了 kanzi::Renderer3D 类。现在您可以通过 Renderer 类访问以下函数：

  • Renderer::applyCameraMatrix

  • Renderer::beginFrame

  • Renderer::disableSubRectangleProjection

  • Renderer::endFrame

  • Renderer::getActiveGraphicsOutput

  • Renderer::getCompositionStack

  • Renderer::getInheritedAspectRatioMultiplier

  • Renderer::getOverrideClusterMaterial

  • Renderer::getOverrideMaterialCallback

  • Renderer::getOverrideMaterialCallbackUserData

  • Renderer::setActiveGraphicsOutput

  • Renderer::setSubRectangleProjection

  • Renderer::setOverrideMaterial

  • Renderer::setOverrideMaterialCallback

  请参阅 Renderer API 的更改。

• 挂起唤醒信号源现在提供了一个接口，您可以使用 WakeupSignalSource 查询该接口。请参阅 对挂起处理的更改。

• 使用 Application 类将事件源附加到域时，不再向主循环调度器注册关联的事件句柄。请参阅 对事件处理的更改。

• 公开了 Windows 动态库中的若干底层函数。

• 更新了若干 Kanzi Engine API 的参数和返回类型，使其使用 size_t 数据类型，而不是 unsigned int。请参阅 对多个 Kanzi Engine API 的更改。

• 将 kanzi::optional (optional.hpp) 和 kanzi::string_view (string_view.hpp) 更改为 std::optional 和 std::string_view。在 Kanzi 的上一个版本中，这些类型在某些平台上为 boost::optional 和 boost::string_view。请参阅 对多个 Kanzi Engine API 的更改。

• 将 kanzi::byte (cstddef.hpp) 更改为 std::byte。在 Kanzi 的上一个版本中，该类型在某些平台上为 unsigned char。请参阅 对多个 Kanzi Engine API 的更改。

• 现在您可以使用 Application::loadKzbFile (ConstByteSpan fileData, bool setStartupPrefab) 从内存缓冲区加载 kzb 文件。在销毁应用程序之前，请保持该内存缓冲区有效。

• 从 CompositionStack 中移除了默认栈状态。所有栈状态都必须显式推入栈中。请参阅 对合成堆栈的更改。

• 移除了已弃用的函数 Renderer::getColorReadFormat 和 Renderer::getColorReadType。请参阅 Renderer API 的更改。

• 移除了已弃用的类 kanzi::TextureSwizzleMask。

• 移除了用于操作节点中标签的抽象类 kanzi::Tag。请参阅 标签的更改。

• 新增了使用 MainLoopScheduler::setCustomSleepFunctionForYield 为 MainLoopScheduler::yield 设置自定义休眠逻辑的功能，以便针对特定平台进行优化。

• 从 CompositionStack 中移除了所有 apply 函数。在所有推入和弹出操作之后，设置会立即自动应用。请参阅 对合成堆栈的更改。

• 新增了用于标准化 PBR 着色器属性的 API 函数。

• 从 Renderer 中移除了 checkGLSupport 和 checkGLESSupport 方法。请参阅 Renderer API 的更改。

• 如果在 TaskDispatcherBase::executeTasks 仍在执行时再次调用它，或者从不属于该调度器的线程调用它，它现在会抛出异常。以前，这两种情况都会导致未定义行为。

• 弃用并移除了 Texture 及相关类型中 RenderTargetMode 的所有痕迹。请参阅 Renderer API 的更改。

• 弃用并移除了 ProgressiveRenderingViewport2D.MultisampleLevel。请参阅 对 Progressive Rendering Viewport 2D 属性的更改。

• 位于 kanzi/core/platform/cpp/win32/string_conversion.hpp 中的 Win32 string 实用工具已从 kanzi 命名空间移至 win32

• 在不存在配置时，Kanzi Engine 应用程序的默认 SurfaceColorSpace 已从 SurfaceColorSpace::sRGB 更改为 SurfaceColorSpace::Standard。该值与新 Kanzi Studio 工程中默认配置的颜色工作流一致。

• 引入了用于管理后备字体链的 FontFamily 和 FontRuntime 方法。

• 更改了 GlyphRun 和 TextFormat 方法的签名。请参阅 文本渲染的更改。

• 为 TriggerTemplate 添加了接口，使您能够向触发器模板添加操作和条件。

活动

• 为 Activity 引入了 OptimizeMemory 参数。启用后，Kanzi 会在这些 Activity 停用后自动卸载其使用的资源。

  请参阅 虚拟化。

• 更改了 ActivityCodeBehind 类：

  • 在 Kanzi C++ API 的 ActivityCodeBehind 类中，将 onActive、onInactive、onActivating 和 onDeactivating 回调替换为 ActivityCodeBehind::onStatusChange。

  • 在 Kanzi C++ (ActivityCodeBehind) 和 Kanzi Java API (ActivityCodeBehind) 中，均移除了 registerStatusChange、registerStatusChangeOverride、unregisterStatusChange 和 unregisterStatusChangeOverride。

  要迁移您的 Kanzi 应用程序，请参阅 ActivityCodeBehind 类的更改。

• 更改了 ActivityElementImpl 和 ActivityHostConceptImpl 类：

  • 从 ActivityHostConceptImpl 类中移除了以下方法：

    • getActiveOrAttachedActivating

    • getAttachedActivityNodes

    • getActivityInfo

  • ActivityElementImpl::onAttachedOverride 方法不再是虚方法。

  由于 ActivityElementImpl 和 ActivityHostConceptImpl 类使用 CRTP 模式，派生类不得重写这些方法。

  要迁移您的 Kanzi 应用程序，请参阅 ActivityElementImpl 和 ActivityHostConceptImpl 类的更改。

• 您不能再手动向 Data-Driven Exclusive Activity Host 添加 Activity。要了解如何使用 Data-Driven Exclusive Activity Host，请参阅 教程：从数据源生成 UI 和 数据驱动独占活动主机。

  要迁移您的工程，请参阅 Data-Driven Exclusive Activity Host 的更改。

• 为 Exclusive Activity Host 引入了 Fallback State。当您不希望 Exclusive Activity Host 中有任何 Activity 处于活动状态时，请使用 Fallback State。

  请参阅 使用回退状态。

  

• Activity 和 Activity Host 的默认对齐设置现在设为在水平、垂直和深度方向上拉伸。

动画 (Animations)

要在 Animation Clip Editor 中设置贝塞尔曲线插值，现在您可以为一个或多个贝塞尔控制柄输入精确值。请参阅 设置关键帧之间的缓动函数。

绑定 (Bindings)

• 您现在可以将布尔型、整数型、浮点型、向量、颜色和矩阵类型用作以下各项的任意参数：

  • 算术运算 +、-、* 和 /。请参阅 算术运算符。

  • 数学函数 限制 (Clamp)、最大值 (maximum)、最小值 (minimum)、mod（模数）、pow（幂） 和 rem（余数）。

  • 插值函数 混合、步进、linearStep、smoothStep 和 smootherStep。

• 属性和绑定中布尔值的字符串转换结果现在为小写的 true 或 false：

  • 在绑定表达式中，将布尔常量隐式转换为字符串的结果现在为小写的 true 或 false，而不是 True 或 False。

  • 在 Kanzi Engine C++ API 中，布尔值到字符串的属性绑定现在写入 true 或 false，而不是 1 或 0。

  请参阅 对属性和绑定的更改。

焦点

现在您可以在自定义焦点范围中覆盖焦点候选项的选择。请参阅 FocusScope::selectFocusCandidate。

Kanzi Engine 应用程序配置

• 移除了 MultisamplePreference 应用程序配置文件选项，因为 Kanzi Engine 不再支持隐式多重采样。

• 现在您可以在应用程序配置中设置表面呈现模式。请参阅 PresentMode。

• 现在您可以在应用程序配置中为 PerformanceInfo HUD 设置字号。请参阅 PerformanceInfoFontSize。

• 添加了一个配置选项，用于为不可缩放字体（例如带有 CBDT 表的彩色字体）指定图形缓存纹理大小。请参阅 图形缓存纹理大小。

Kzb 版本 (Kzb Version)

将 kzb 文件格式版本更改为 36.0。

列表框 (List Box)

重命名了以下 List Box 消息：

• List Box: Item Hidden 改为 List Box: Item Unloaded

• List Box: Item Visible 改为 List Box: Item Loaded

要迁移您的 Kanzi 应用程序代码，请参阅 列表框的更改。

列表框节点 (List Box nodes)

默认的方向导航键现在可以在 Grid List Box 和 Trajectory List Box 3D 节点中移动按键焦点。请参阅 在 List Box 节点中处理键焦点。。

要迁移您的应用程序，请参阅 列表框节点的更改。

渲染 (Rendering)

• 将 Legacy 颜色工作流重命名为 Standard，它现在也是新工程的默认设置。请参阅 颜色工作流程。

• Kanzi 现在将 24 位 RGB PNG 和 JPEG 图像以带有默认 Alpha 通道的 RGBA 格式加载到内存中。

• 现在您可以为 2D 节点自动生成的合成目标指定 Mipmap 模式。要在合成时生成 mipmaps，请设置 2D 节点的 Mipmap Mode 属性 (Node2D::MipmapModeProperty)。默认操作保持不变，不会生成 mipmaps。

  如果您使用 Render Target 属性 (Node2D::RenderTargetProperty) 显式指定合成目标，则以该纹理中设置的 Mipmap 模式为准。

  此更改还修复了在对合成结果执行 blit 之前未生成 mipmaps 的问题。

• Factory Content 现在包含 Skybox Render Pass，您可以使用它在 3D 场景中绘制立方体贴图背景。

• 在应用程序配置中，Preferred Vulkan GPU 选项的默认值现在设置为使用 First 枚举设备。这使用户可以控制设备选择，通常通过控制面板应用程序进行。要恢复之前的行为，请使用 LargestMemory 选项。

• 将 kanzi::GlRenderState 类重命名为 RenderState，以移除特定于平台的 “Gl” 前缀。渲染状态抽象并非特定于 OpenGL。请参阅 引入 Kanzi Graphics。

跟踪 (Tracing)

为 Kanzi Engine 添加了跟踪系统。跟踪系统可用于检查 Kanzi Engine 的内部机制，并帮助您识别性能问题。跟踪系统取代了性能分析系统。Release 构建中禁用了跟踪。请参阅 Tracing 和 跟踪 (Tracing)。

Kanzi Engine Lua API

• 接受 PropertyType 参数的函数在传入其他类型的对象时，不再通过返回 nil 静默失败，而是终止脚本执行并记录一条警告。

• 添加了包含 Kanzi 日志函数的 log 模块。请参阅 日志。

• 添加了用于访问和修改 DataObject 树的 DataSource 方法。

Lua 数据源 (Lua Data Source)

现在您可以在 Kanzi Studio 中使用 Lua 脚本，在设计的同时定义和模拟应用程序的外部数据依赖项，而无需编写或编译任何原生代码。请参阅 使用 Lua 定义数据源。

窗口管理 (Windowing)

• 对于 Wayland 后端，添加了忽略合成器发送的 frame() 事件并立即处理输入的选项。当合成器未正确发送 frame() 事件时，这将非常有用。请参阅 Wayland 输入模式。

• 您现在可以以编程方式设置 QNX Screen 属性的使用标志。请参阅 QnxUsageFlags。

更改

• Kanzi 现在需要 Visual Studio 2022。Kanzi 不再包含适用于 Visual Studio 2017 和 2019 的库。请参阅 升级到 Visual Studio 2022。

• Kanzi 现在需要 C++17。

• 将 Boost 从 1.77.0 更新到 1.85.0。

• 将 libjpeg 9d 替换为 libjpeg-turbo 3.0.3。

• Page 和 Page Host 节点已弃用，并将在 Kanzi 的下一个版本中移除。请参阅 弃用 Page 和 Page Host 节点。

• 将 ICU 库从 62.1 版本升级到 69.1 版本。移除了未使用的 ICU 数据和功能，根据目标平台的不同，库文件大小最多可减小到原来的四分之一。

• 移除了用于压缩纹理的 ATC 和 PVRTC 算法。

• 在标签不发生变化的情况下，使用标签过滤 NodeList 时的渲染性能显著提升。

• 标签属性不再可继承，并且更改标志包含一个单独的标志，用于表示标签状态已更改。这导致使用旧标签设置导出的旧 KZB 不再兼容。KZB 版本号已递增。

• 当渲染的变形数量足够少、无需使用数据纹理时，变形数据现在完全交错存储。

• 现在，您可以将 Keep Alive Behavior 属性添加到 Fonts。这样，即使字体未被使用，您也可以将字体文件保留在内存中。请参阅 设置 Kanzi Engine 如何处理单个未使用的资源。。

• 更新了应用程序配置对布尔值的处理。Kanzi 现在仅接受 false、true、0 和 1 作为布尔配置选项的有效值。

• 为清晰起见，重命名了引用 OpenGL 上下文 API 的实体：

  • kanzi::platform::OpenGLPlatform 已重命名为 kanzi::platform::GlContextApi；

  • kanzi::platform::createDefaultOpenGLPlatform 已重命名为 kanzi::platform::createDefaultGlContextApi。

• 将 Monotype iType 库更新到 6.3.1 版本，WorldType Shaper 更新到 5.3 版本。

• 将所有平台迁移为使用 CMake 而不是 SCons。

• 将 kanzi::Mesh 的索引缓冲区合并为 Mesh 对象自身中的一个缓冲区，而不是每个 kanzi::Mesh::Cluster 各自拥有索引缓冲区。

• 为跟踪系统添加了基于帧的间隔选项。请参阅 TracingFrameInterval 和 TracingTimeInterval。

• 重命名了 TracingInterval 配置选项。请参阅 对应用程序配置的更改

• 移除了 Level Of Detail 节点。

• 添加了 KZ_EXPERIMENTAL 宏，用于标记在未来版本中可能更改的功能。

显著修复

Kanzi Engine

• 修复了导致 Kanzi Engine 在滚动期间无法通过 Scroll Position 属性覆盖 Scroll View 位置的问题。(FMW-688)

• 修复了当某个 Actions 再次触发同一 Message Trigger 时，导致 Kanzi 在该 Message Trigger 中错误地转发消息参数的问题。(FMW-707)

• 修复了无法在 constexpr 函数中使用 kzAssert 宏的问题。(454808)

• 修复了当 kzCameraNormalMatrix uniform 具有平移组件时，getCameraNormalMatrix 着色器统一绑定函数返回不正确矩阵的问题。(RENDERING-570)

• 修复了导致 Kanzi Engine 在并行活动主机或独占活动主机中激活的活动尝试使用 On Attached 触发器自行停用时终止或行为不正确的问题。(SDK-9210)

• 在 2D 节点中，在第一次布局传递之前，Actual Width 和 Actual Height 属性现在被正确设置为 0.0 而不是 inf。(RENDERING-589)

• 修复了当节点使用非透明颜色覆盖 Color Brush 的透明 Brush Color 属性值时，导致 Kanzi 无法渲染该 Color Brush 的问题。(RENDERING-596)

• 修复了在运行时更新 Blend Mode 属性值时导致 Kanzi 在 2D 节点中使用错误混合模式的问题。(RENDERING-597)

• 修复了导致 Kanzi 在 GPU 资源失效后无法重新加载渲染目标 Texture 的问题。(RENDERING-669)

• 修复了在数据触发器条件表达式中使用简单数据源绑定时导致 Kanzi Engine 终止的问题。(SDK-9232)

• 修复了一个问题，该问题阻止 Kanzi 渲染之前未使用内容纹理渲染的 Texture Brush 的内容纹理。(RENDERING-683)

• 修复了 Texture Brush 渲染中的问题，该问题导致 Kanzi 忽略 Brush Vertical Tiling 和 Brush Horizontal Tiling 属性值的更改。(RENDERING-675)

• 修复了导致 kzWindowSize uniform 在屏幕节点的绝对大小小于帧缓冲区大小时不等于屏幕节点大小的问题。(RENDERING-415)

• 修复了导致 Kanzi 错误地为不支持任何二进制着色器格式的目标平台禁用着色器二进制缓存的问题。着色器二进制缓存仅需要着色器二进制程序。(RENDERING-693)

• 修复了启用 Word Wrap 属性并设置了 Horizontal Margin 属性的 Text Block 节点无法在垂直排列的 Stack Layout 中正确显示的问题。(SDK-8946)

• 修复了 Node::lookupNode 函数无法处理通过 Node::getPath 函数获取的绝对路径的问题。(SDK-9570)

• 修复了 Kanzi 应用程序从休眠中唤醒后恢复合成目标的问题。(RENDERING-1772)

• 修复了导致 iType 字体渲染器在使用某些字体时无法渲染阿拉伯语变音符号的问题。(SDK-9968)

• 修复了导致 Object::getDynamicMetaclass 方法对 StateManager 和 PrefabTemplateNode 资源返回基类 Resource 元类的问题。(SDK-9987)

• 修复了在调试模式下向 Text Box 输入某些内容时导致 Kanzi Engine 因断言而终止的问题。(SDK-10001)

• 修复了导致 WindowsImeBackend 无法处理包含 Unicode 增补字符的按键输入的问题。(FMW-128)

• 修复了导致 Text Box 光标渲染到错误位置的问题。(SDK-9952)

• 修复了导致使用 kzProfiling* 宏的文件中出现对齐错误的问题。(INTE-833)

• 修复了导致 Kanzi 在 Performance HUD 中缺少 Timer 订阅数和 Recurring Tasks 数信息的问题。(FMW-58)

• 修复了在使用复杂文字时导致 Kanzi 在 Text Box 中错误地选择和删除字符的问题。(FMW-127)

Kanzi Studio

• 修复了在创建使用内置材质的 BlitRenderPass 时导致 Kanzi 导入 DefaultBlitMaterial 的问题。(FMW-416)

• 修复了以下绑定问题 (FMW-553)：

  • 修复了当源节点的父节点被重新指定父节点或重命名，或者源节点本身在重新打开工程后被重新指定父节点时，绑定源属性的修改无法更新目标属性的问题。

  • 修复了当源节点的父节点被移入预设件时，无法对含有绑定的节点进行验证的问题。

• 修复了在 Binding Editor 中使用撇号字符 ' 时导致 Kanzi Studio 在调试模式下因断言错误而失败的问题。(EDITORS-320)

• 修复了按住 Shift 键时导致 Kanzi Studio 丢失在 UI 下拉列表中输入的字母的问题。(EDITORS-292)

• 修复了在创建目标属性类型为 < Null > 的绑定时导致 Kanzi Studio 终止的问题。(FMW-632)

• 修复了当工程名称包含短横线或空格等不合规字符时，导致 Kanzi Studio 在应用程序代码中生成错误 KZB 名称的问题。(FMW-620)

• 修复了导致 Kanzi Studio 偶尔无法加载以命令行参数指定的工程的问题。(FMW-585)

• 修复了在解决 Smart Materials 的工程合并冲突时，导致 Kanzi Studio 因运行时异常而终止的问题。(FMW-671)

• 修复了 Activity Browser 中的以下问题，这些问题在下列情况下导致 Kanzi Studio 因异常而终止：

  • 您尝试创建名称以 . 字符开头或结尾、或包含多个相邻 . 字符的 Activity Property。(FMW-618)

  • 您尝试为名称包含文件名中不允许的字符的 Activity 添加 C++ Code Behind。(FMW-722)

• 修复了当您尝试撤销对带有绑定的节点执行的更改父项命令时，Kanzi Studio 向 Log 窗口打印错误消息的问题。(FMW-691)

• 修复了 Kanzi Studio 中在 Code Behind 构建失败时无法将 CMake 错误输出到 Log 窗口的问题。(FMW-720)

• 修复了重命名工程时导致 Kanzi Studio 在工程目录中保留使用旧文件名的工程清单文件的问题。(FMW-735)

• 修复了从工程中删除 FBX 文件时导致 Kanzi Studio 使网格数据失效并报告属性 Imported from 引用了无效路径的问题。(FMW-692)

• 修复了导致 Kanzi Studio 在工程文件中重复网格数据的问题。(FMW-78)

• 修复了加载名称以资源文件目录名开头的工程时导致 Kanzi Studio 终止的问题。(FMW-783)

• 修复了 Kanzi Studio 中在重命名包含子项的工程项后无法从文件系统中删除旧目录的问题。(FMW-721)

• 修复了 Kanzi Studio 中在 Studio UI 已禁用时仍允许您使用快捷键的问题。(FMW-804)

• 修复了导致 Kanzi Studio 在导出和导入 kzb 文件时使用 Kanzi Engine Java 插件文件的绝对路径的问题。(ANDROID-380)

• 修复了在 100% 缩放的 Kanzi Studio 预览中导致 gl_FragCoord 和 kzWindowSize uniform 不正确的问题。(RENDERING-415)

• 在 Kanzi 默认基于物理的材质类型中，当您启用 KANZI_SHADER_RECEIVE_POINT_SHADOW 预处理器定义时，Kanzi Studio 不再无法为 PointShadowMap 自定义属性类型创建绑定。(RENDERING-626)

• 激活多个变形目标有时会导致 Kanzi Studio 生成的变形目标法线出现逐渐加剧的视觉质量下降。要解决此问题，您现在可以使用 KANZI_SHADER_USE_MORPH_NORMAL_LIMIT 预处理器定义。请参阅 使用变形目标法线。(RENDERING-772)

• 在 On Property Changed 触发器中，如果您未将 Property Type 设置为正确的值，Kanzi 现在会将其标记警告。(PRODUCT-354)

• 修复了在仅导入非 HDR 图像时，Texture 文件夹上下文菜单中的 Import Images 命令导致导入时间增加并打印警告的问题。(PRODUCT-1185)

• 修复了将字体文件导入到 Library > Font Families > <FolderName> > Font Family 时导致 Kanzi Studio 终止的问题。(SDK-9963)

• 修复了导致 Kanzi Studio 将 Font Family 中已删除的 Font File 标记为 ProjectItemReference: null ABSOLUTE 而不是将其完全移除的问题。(SDK-9902)

• 修复了将绑定从一个预设复制到另一个预设时导致 Preview 终止的问题。(PRODUCT-1291)

• 修复了 Preview 关闭期间遗留未释放资源的问题。(PRODUCT-1282)

• 修复了快速打开下拉列表时工具提示与下拉列表重叠的问题。(PRODUCT-1294)

• 修复了导致 Kanzi Engine 插件中定义的 Action 显示不正确的问题。(PRODUCT-1302)

• 修复了阻止 Kanzi Studio 导入资产的 mipmap 的问题。(PRODUCT-1299)

• 修复了将材质拖放到 Preview 窗口时导致 Kanzi Studio 将材质分配给错误群集的问题。(PRODUCT-1026)

• 修复了无法在 Kanzi Studio 工程之间共享群集材质 (Cluster Materials) 的问题。(PRODUCT-800)

• 修复了阻止在子节点上为 State Manager 的控制器属性添加迁移的问题。(PRODUCT-1317)

• 修复了使用位图格式不正确的图像文件为 HDR 立方体贴图生成纹理时导致 Kanzi Studio 终止的问题。(PRODUCT-1340)

• 修复了首次尝试重新激活限时订阅许可证时导致 Kanzi Studio 显示错误的问题。(PRODUCT-1349)

• 修复了在 Kanzi Studio 外部更改着色器文件后，阻止 Kanzi Studio 更新并应用该着色器文件的问题。(PRODUCT-1353)

• 修复了导致 Kanzi Studio 在工程文件中保留已删除的立方体贴图并将其导出到 kzb 文件的问题。(PRODUCT-1323)

• 修复了撤消资产导入时导致 Kanzi Studio 终止的问题。(PRODUCT-1368)

• 修复了在导入元数据有误的 Kanzi Engine 插件时导致 Kanzi Studio 挂起的问题。(FMW-50)

• 修复了阻止 Kanzi Studio 导入从其他工程合并的立方体贴图纹理文件的问题。(FMW-79)

• 修复了在使用自定义显示缩放系统设置时，导致 Bindings Editor 中行号与其对应文本错位的问题。(EDITORS-56)

• 修复了 Kanzi Studio 中在 Library 中重命名动画剪辑后，Animation Clip Editor 窗口标题未相应更新的问题。(EDITORS-55)

• 修复了在未按下 Ctrl 的情况下进行选择时，导致 Kanzi Studio 中 Animation Clip Editor 的 Move tool 保持选中多条曲线的问题。(EDITORS-11)

• 修复了 Kanzi Studio 中重新打开工程后，始终将工具提示中含有换行符的 Kanzi Engine 插件元数据标记为过期的问题。Kanzi Studio 现在还会在元数据包含不受支持的字符时发出警告。(FMW-261)

• 修复了阻止在 Kanzi Studio 中打开 Related Items 窗口的问题。(EDITORS-130)

• 修复了 Kanzi Studio 的 Animation Clip Editor 中第一个拖放的属性被直接添加为 Animation Clip 的子项，而不是添加到其所属节点下的问题。(EDITORS-132)

• 修复了 Kanzi Studio 的 Related Items 窗口中绑定显示不正确的问题。(EDITORS-52)

• 修复了 Kanzi Studio 在 Preview 启动期间无法报告 Code Behind 构建通知的问题。(FMW-202)

• 修复了启用编辑模式时，导致 TextBox3D 节点在 Preview 窗口中处理用户输入按键的问题。(FMW-289)

• 修复了在使用 Kanzi Graphics 渲染器且选择背景颜色的 alpha 设置为零时，导致 TextBox3D 错误渲染所选文本的问题。(FMW-355)

• 修复了在 Win32 上导致 WriteOnlyDiskFile 错误处理包含非 ASCII 字符的文件名的问题。(EDITORS-288)

Kanzi Android framework (droidfw)

• 修复了基于 Kanzi Android framework (droidfw) 的视图在收到来自 Android 的多点触控手势取消后停止处理用户输入的问题。(ANDROID-1386)

• 修复了 KanziViewAdapter 实例在使用 KanziViewAdapter.handleVisibilityChange 隐藏后，仍继续渲染并处理用户输入的问题。(ANDROID-1317)

• 修复了在基于 Kanzi Android framework (droidfw) 的应用程序中 Performance HUD 位置不正确的问题。(ANDROID-1166)

Kanzi Engine Lua API

• 通过在 Kanzi 安装中包含必要的依赖项，修复了导致 Kanzi Engine Lua API 静态链接失败的问题。(ANDROID-1630)

平台

• 修复了在空闲状态 (Idle State) 下轮询 Wayland 事件时导致 libwayland 内部环形缓冲区溢出的问题。(INTE-806)

• 修复了 Wayland 上的触摸问题：在调试模式下编译时，如果在同一触摸帧内重复使用触摸 ID，会导致 Kanzi 因断言而终止。(INTE-795)

另请参阅

Kanzi 4.0.0 迁移指南

已知问题