Kanzi 4.1.2 版本说明¶

跟踪 (Tracing)¶

Profiling 或 Debug 构建的跟踪现在会显示 Kanzi Engine 对 3D 节点和文本进行布局所花费的时间。请参阅 Tracing。
- 每次 Kanzi Engine 测量或排列 3D 节点时，跟踪都会显示 <node name> Node3D::measure 或 <node name> Node3D::arrange 作用域，与 2D 节点的 <node name> Node2D::measure 和 <node name> Node2D::arrange 作用域类似。
- 每次 Kanzi Engine 对文本进行布局时，跟踪都会显示 TextLayouter::createLayout 作用域。
  
  备注
  
  Performance HUD 在每一帧中都会对其文本进行布局，因此跟踪中也会显示它的 TextLayouter::createLayout 作用域。要仅跟踪您的应用程序的文本，请关闭 Performance HUD。
由于这些作用域，对于在每一帧中都对大量 3D 节点或文本节点进行布局的应用程序，其跟踪会更快地占满跟踪内存。要在跟踪中保留相同数量的帧，请增大 TracingSampleMaxMemory。请参阅 TracingSampleMaxMemory。
Profiling 或 Debug 构建的跟踪现在会在 Resource CPU Memory (kb) 和 Resource GPU Memory (kb) 采样旁边显示 Resource count 采样，其中包含资源管理器所持有的资源数量。

3D 节点布局优化¶

当某个同级节点重新对其内容进行布局时，Kanzi Engine 不再重新计算未更改的 3D 节点及其后代节点的变换。这适用于其父节点不对子节点进行布局的 3D 节点，例如 Empty Node 3D 或 Scene 下的节点。例如，当数据源更改同一 Empty Node 3D 下众多 Text Block 3D 节点中少数几个节点的文本时，更新速度会更快。

3D 节点变换优化¶

现在，当 3D 节点移动时，Kanzi Engine 更新 3D 节点变换所花费的 CPU 时间更少。例如，这会使平移由 3D 节点构成图块、道路和标签的地图变得更快。

焦点优化¶

在包含大量节点的应用程序中，切换节点的可见性现在更快。此前，每当节点的 Visible 属性更改时，Kanzi Engine 都会在节点树中搜索已聚焦的节点。已聚焦节点之前的节点越多，搜索耗时越长，例如 Viewport 2D 中大型 3D 场景的节点。现在，Kanzi Engine 仅在您隐藏可聚焦节点或焦点范围 (Focus Scope) 节点时，或者隐藏或显示节点改变了拥有焦点的覆盖层范围时，才会进行搜索。请参阅 FocusManager。

属性系统优化¶

读取和设置节点及其他 Kanzi 对象的属性现在更快。Kanzi Engine 现在能更快地找到属性的存储位置，并且每次读取属性时只查找一次。这会更改 PropertyObject 及其所有派生类的大小，因此请针对 Kanzi 4.1.2 重新构建您的 Kanzi Engine 插件和应用程序。

请参阅 Kanzi 4.1.2 迁移指南。

文本布局优化¶

使用 FreeType 字体引擎（默认字体引擎）时，Kanzi Engine 现在对文本进行布局所花费的 CPU 时间更少，例如每次数据源更改文本节点的文本时，或者文本使用其字体文件之前已使用过的 Font Size 时。请参阅 FontEngine。
现在，当父节点重新对 Text Block 2D 或 Text Block 3D 节点进行布局时，Kanzi Engine 对该节点进行布局所花费的时间更少。当影响该节点布局的属性均未更改时，Kanzi Engine 不再检查该节点是否需要新的文本布局。这适用于未使用 Word Wrap、Overflow 或 Truncation 的节点。

因此，Kanzi Engine 调用 TextBlockConceptImpl::onPostPrepareTextFormat 的次数更少。当此类属性均未更改时，Kanzi Engine 不会调用该函数。当其中某个属性更改时，Kanzi Engine 在每次布局过程中只调用该函数一次，而不是两到三次。如果您的 Text Block 类在该函数中更改节点的文本或字体属性，该节点会保留其之前的文本布局。请在布局之外进行此类更改，例如在主循环任务中。

备注

当您的应用程序移除或替换设置 Text Block 节点文本或字体属性的状态机时，该节点会保留其之前的文本布局和大小。当您的应用程序重命名状态对象 (State Object) 的目标节点时，也会发生同样的情况。要更新该节点，请对其调用 Node::invalidateMeasure。在 Preview 中，当您从状态中移除文本或字体属性时也可能发生这种情况。要更新 Preview，请重新启动它。

文本渲染优化¶

现在，当 Text Block 3D 节点的文本中没有彩色字形（例如表情符号）时，Kanzi Engine 渲染该节点的速度更快。对于此类文本，Kanzi Engine 会跳过使用 Color Font Material 进行渲染。请参阅彩色字体。
使用 Vulkan 时，Kanzi Engine 首次以之前未使用过的 Font Size 渲染某个字体文件的文本时，所花费的时间更少。为了清除该字号对应的新字形缓存纹理，Kanzi Engine 现在使用 GPU，而不是上传全零纹理。
现在，当文本在其节点内移动或缩放但文本本身保持不变时，Kanzi Engine 为渲染准备文本所花费的 CPU 时间更少。Kanzi Engine 会重用文本的渲染数据，而不是重新创建。例如，这适用于以下情况：
- 您更改 Text Block 或 Text Box 节点的对齐方式或内边距。
- Horizontal Fit 将文本缩放到新的宽度。
- 用户通过移动光标滚动 Text Box 节点的文本。
每次 Kanzi Engine 创建文本的渲染数据时，Profiling 或 Debug 构建的跟踪都会显示 TextFormat::createGlyphRuns 作用域。请参阅 Tracing。

备注

Performance HUD 在每一帧中都会创建其文本的渲染数据，因此跟踪中也会显示它的 TextFormat::createGlyphRuns 作用域。要仅跟踪您的应用程序的文本，请关闭 Performance HUD。

渲染 (Rendering)¶

现在，您可以将 Format 为 Alpha 8-bit (A8_UNORM) 的 Render Target Texture 设置为 2D 节点的 Render Target 属性，从而将该 2D 节点渲染到该纹理。Kanzi Engine 将片段着色器 (Fragment Shader) 输出的红色分量写入该纹理，着色器会将该值作为 alpha 读取。Composition Target 渲染通道仍会丢弃此类纹理并发出警告。对于多重采样渲染目标纹理以及在 WebGL 上，Kanzi Engine 仍会记录警告并跳过帧缓冲区附件。

Kanzi Engine C++ API¶

添加了接受所有者参数的 PropertyObject::addDestroyCallback 重载，以及 PropertyObject::removeDestroyCallback。当销毁回调的所有者可能先于属性对象被销毁时，请使用它们，以便所有者能够先移除其回调。

文档 (Documentation)¶

新增了相关说明，介绍在 Kanzi Android framework (droidfw) 中没有活动的 Kanzi 视图时，您提交到 TaskDispatcher 的任务会如何处理。这些任务会等待，并在某个视图重新变为活动状态后的第一帧中由 Kanzi 全部执行。如果应用程序在没有活动视图时为数据源的每次更新都提交一个任务，可能会使第一帧延迟数秒。文档介绍了如何避免任务堆积。请参阅在没有活动视图时提交任务。
新增了 Kanzi Portal MCP 服务器的说明。该服务器将您的 AI 助手连接到您的 Kanzi 帐户，使您可以查询和管理您的许可证、组织、下载和支持工单。请参阅 Kanzi Portal MCP 服务器。此外，还在使用 Kanzi AI 工具中新增了 Kanzi MCP 服务器的快速设置说明。
Kanzi 文档现在也提供简体中文和日语版本。译文由 AI 生成，以英文文档为准。每个翻译页面都会注明这一点，并链接到对应的英文页面。API 参考、生成的参考（例如节点和资源参考）以及许可证文本均为英文，翻译页面会链接到英文 API 参考。

显著修复¶

Kanzi Engine¶

修复了以下问题：每次 Kanzi 将绑定附加到在两次附加之间一直保持存活的节点或资源时，内存使用量都会增长。该问题由 Kanzi 4.0.0 引入。(FMW-1643)

例如，在以下情况下会发生此问题：
- 应用程序分离某个节点后又重新附加该节点。
- 带有数据源绑定的节点的数据上下文发生了更改。
- 应用程序重新创建了绑定到实例外部的节点、数据对象或材质的预设件实例。
修复了以下问题：当跟踪中没有任何事件时（例如应用程序在清除跟踪后立即写入跟踪），Kanzi Engine 写入的跟踪文件不是有效的 JSON。Chrome tracing 和 Perfetto 等跟踪查看器无法加载此类文件。(FMW-1690)
修复了以下问题：使用 FreeType 字体引擎时，对于 FreeType 拒绝的字号，FreeTypeFontFile::setSize 仅在第一次调用时抛出异常。此后，Kanzi Engine 会以该字号错误地对文本进行布局而不抛出异常，例如使用 TextLayouter 时。(FMW-1753)
修复了以下问题：Kanzi Engine 为每个窗口表面创建单独的 EGL 上下文。这会增加驱动程序的内存使用量，例如在 Qualcomm Adreno GPU 上。Kanzi Engine 现在对所有窗口表面使用同一个 EGL 上下文。该问题由 Kanzi 4.1.0 引入。(RENDERING-3483)
修复了每次应用程序销毁并重新创建 Kanzi Engine 时原生内存和 GPU 内存使用量增长的问题。例如，当 Android 应用程序重新创建其 Kanzi 视图时会出现这种情况。现在 Kanzi Engine 在关闭时销毁其 EGL 上下文。该问题由 Kanzi 4.1.0 引入。(INTE-1336)
修复了使用 OpenGL 的应用程序在 Qualcomm Adreno GPU 上销毁使用纹素缓冲区纹理的资源集后终止的问题，例如在应用程序切换粒子效果时。(RENDERING-3556)
修复了使用 kzTraceInstant 宏的应用程序代码在不含跟踪的构建（例如 Release 构建）中无法编译的问题。(FMW-1683)

Kanzi Android framework (droidfw)¶

修复了每次基于 Kanzi Android framework (droidfw) 的视图收到既未更改表面也未更改其大小的表面更改时导致原生窗口泄漏的问题。每次创建 KanziSurfaceView 或 Kanzi Android Service 客户端视图的表面之后都会发生此类更改，例如在设备旋转时。该问题由 Kanzi 4.0.0 引入。(ANDROID-2243)
修复了基于 Kanzi Android framework (droidfw) 的视图在没有表面时收到方向更改或表面销毁而导致应用程序终止的问题。在 Kanzi Android Service 宿主中，这会终止该宿主的所有客户端应用程序。(ANDROID-2262)

例如，在以下情况下会发生此问题：
- 应用程序将 onConfigurationChanged 转发给尚未收到其表面或已在后台丢失其表面的视图。
- 在跨应用程序迁移期间，Kanzi Android Service 客户端的表面先于叠加层表面到达。

Kanzi Android Service¶

修复了 Kanzi Android Service 宿主在客户端应用程序处于后台时重新启动后反复终止的问题。现在 Kanzi Android Service 宿主重新启动时，客户端应用程序不再终止。它们会重新连接到重新启动的 Kanzi Android Service 宿主，由宿主再次加载其内容。客户端应用程序在重新启动之前推送的数据会丢失，因此请在 onServiceConnected 中再次推送这些数据。(ANDROID-2256)
修复了 Kanzi Android Service 宿主在 KanziServiceSurfaceView 或 KanziServiceComposable 客户端显示在屏幕上时重新启动后反复终止的问题。之后 Android 会在 30 分钟内停止重新启动 Kanzi Android Service 宿主。(ANDROID-2268)
修复了以下问题：在 host 预加载客户端预设件后，如果另一个客户端应用程序失去其窗口，Kanzi Android Service host 的调试 (Debug) 构建会终止。对于预加载的客户端应用程序，KanziServiceViewAdapterListener.onAttachedToWindow 现在会在其客户端视图附加到窗口时触发，而不再在预加载期间触发。(ANDROID-2206)

预加载的客户端视图在其预设件加载后不再处于活动状态，因此 Kanzi Android Service 宿主应用程序提交给任务调度程序的任务会等待，直到某个客户端视图变为活动状态。请参阅在没有活动客户端视图时提交任务。
修复了跨应用程序迁移有时无法结束的问题。迁移叠加层会一直留在屏幕上，并且 Kanzi Android Service 会忽略该客户端应用程序之后的窗口和表面事件。现在，当用户在迁移结束之前离开客户端应用程序，或者目标客户端应用程序始终不显示其视图时，迁移也会结束。请参阅设置跨应用程序迁移动画。(ANDROID-2245)

KanziServiceTextureView 不支持跨应用程序迁移，因为 TextureView 没有 SurfaceControl。现在 KanziServiceTextureView 的 startSeamlessTransition 会抛出 UnsupportedOperationException，而不是开始一个永远不会结束的迁移。
修复了将 KanziServiceSurfaceView、KanziServiceTextureView 或 KanziServiceComposable 从其窗口中移除、重新添加后再次移除时导致客户端应用程序终止的问题。重新添加的视图也会保持为空。例如，在使用 fragment、ViewPager、RecyclerView 和 LazyColumn 时会出现这种情况。现在，客户端视图在附加到窗口时连接到 Kanzi Android Service，而不是在您填充（inflate）它或调用 connect 时连接，并在分离时断开连接。现在每次视图重新附加时都会再次触发 KanziServiceClientListener.onServiceConnected，并且客户端会丢弃您在视图分离期间进行的调用。现在，当 KanziServiceTextureView 从其窗口分离时，Kanzi Android Service 宿主会调用 KanziServiceViewAdapterListener.onDetachedFromWindow。(ANDROID-2265)

请参阅客户端视图生命周期和 Kanzi 4.1.2 迁移指南。
修复了跨应用程序迁移回某个客户端应用程序后，Kanzi Android Service 停止为该客户端应用程序进行渲染和处理输入的问题。当迁移中的另一个客户端应用程序在后台终止时会出现这种情况，例如 Android 为释放内存而停止了它，或者您强制停止了它。现在，当屏幕上的客户端应用程序终止时，Kanzi Android Service 会为迁移中的另一个客户端应用程序保留内容。请参阅客户端应用程序终止。(ANDROID-2263)
修复了以下 Kanzi Android Service 问题 (ANDROID-2207)：
- 当 Kanzi Android Service 宿主已使用 KanziServiceRuntime.handleVisibilityChange 隐藏客户端应用程序的预加载内容时，该客户端应用程序不显示任何内容且不接收输入。现在，当客户端应用程序提供其表面时，会显示该内容。
- 在预加载内容的预设件加载完成之前隐藏或显示该内容会使加载停滞。
- 在没有表面的情况下显示预加载的客户端应用程序，会导致 Kanzi Android Service 宿主的调试构建在另一个客户端应用程序丢失其窗口时终止。
- 当客户端应用程序为已有表面的内容提供其表面时，Kanzi Android Service 宿主会泄漏一个表面。
- 当客户端应用程序或 Kanzi Android Service 宿主更改没有内容的客户端的可见性时（例如在其客户端视图附加到窗口之前或分离之后），Kanzi Android Service 宿主会终止，在 Release 构建中也是如此。现在 Kanzi Android Service 会忽略此类可见性更改。
修复了 KanziServiceRuntime.preloadClientPrefab 加载客户端应用程序注册的启动预设件而不是预加载预设件的问题。当预设件 URL 为空时，Kanzi Android Service 宿主会在客户端应用程序提供其表面时终止。现在 preloadClientPrefab 会加载预加载预设件，并在预设件 URL 为空时保留客户端应用程序的启动预设件。(ANDROID-2246)
修复了当客户端应用程序向不存在的数据源推送数据时（例如数据源 URL 输入错误或 kzb 文件未加载），Kanzi Android Service 宿主及其所有客户端应用程序终止的问题。现在宿主会记录错误并继续运行。(ANDROID-2261)

Kanzi Studio¶

修复了工程无法覆盖系统着色器的问题。现在，工程 Shaders 目录中与系统着色器路径相同的文件会在所有位置替换该系统着色器，包括其他系统着色器和 Kanzi Studio 提供的材质类型。现在 Clone To Project 会保留系统着色器的路径，因此克隆会覆盖系统着色器。要使使用早期版本 Kanzi Studio 创建的克隆覆盖系统着色器，请将其移动到该系统着色器所在的路径。(RENDERING-3549)

这可能会改变现有工程所使用的文件。工程中已位于系统着色器路径的文件现在会替换该系统着色器。#include <file.glsl> 现在会先在 Shaders 目录中查找文件，然后才查找包含该 #include 的着色器旁边的文件。

请参阅将系统着色器克隆到工程。

文档 (Documentation)¶

修复了渲染最佳实践中声称 Kanzi 不会变换禁用了 Visible 属性的 3D 节点的问题。自 Kanzi 4.1.0 起，Kanzi Engine 会变换这些节点及其子节点，因此隐藏 3D 节点并不能节省 Kanzi Engine 变换该节点所花费的时间。要跳过变换 Viewport 2D 节点的 3D 内容，请禁用 Scene 节点或 Viewport 2D 节点的 Visible 属性。(FMW-1770)
修复了文档中声称 Kanzi Android framework (droidfw) 和 Kanzi Java API 需要 Java 8 的问题。自 Kanzi 4.0.0 起，它们需要 Java 语言级别 11 或更高。同时修复了使用 Kanzi Android framework (droidfw) 项目进行工作中的 Groovy 示例，该示例使用了 Gradle 未定义的 JavaVersion.VERSION_1_11。(ANDROID-2271)

另请参阅¶

Kanzi 4.1.2 迁移指南

已知问题