Kanzi 4.1.0 版本说明

更改

• 将 CMake 的最低版本要求提高到 3.25。

  在 Android 工程中，Gradle 设置为使用 CMake 3.30.5 版本，因为这是 Android SDK 提供的最低兼容版本。

• 为符合 CMake 3.27 中引入的 CMake 策略 CMP0144，CMake 提示变量 KANZI_ROOT 已重命名为 Kanzi_ROOT。

  如果您的工程或构建环境通过设置 KANZI_ROOT 来定位 Kanzi 安装，请将其重命名为 Kanzi_ROOT。请参阅 构建系统的更改。

• 为 Value Accumulators 添加了逐帧递增模式。现在，您可以将 Value Accumulator 配置为每帧递增一次其值，而不是基于时间间隔递增。

  要使用逐帧递增模式，请将 Value Accumulator 的 Increment Mode 属性设置为 Per Frame。在此模式下，Value Accumulator 会忽略 Increment Time Interval 属性，并在每一帧将累加值增加输入值。

  请参阅 增加属性类型的值。。

• 重构了列表框类，以简化自定义实现。

  请参阅 列表框的更改

• Kanzi Studio 现在从 <KanziInstallation>/Studio/Asset Library/MaterialTypes 工程导入默认材质，而不再从 .kzmat 文件导入。

• 在 Kanzi Studio 的 Preview 窗口中，按住 Alt 键现在可以在 Camera tool 和 Node tool 之间切换。

• 在 Kanzi Studio 中截取 Preview 屏幕截图时，不再捕获选择轮廓。

• 在 Binary Export 工程设置中添加了 Target Shader Family 属性。使用此属性可设置 Kanzi Studio 在 kzb 文件中包含哪些着色器系列。默认情况下，Kanzi Studio 包含全部三个系列：OpenGL、OpenGL ES 和 Vulkan。移除目标平台不使用的系列可以减小 kzb 文件的大小。

  请参阅 设置要导出的着色器系列。

• 现在，您可以直接在绘图对象渲染通道 (Draw Objects Render Pass) 中对渲染条目进行排序，而无需将对象源用作排序的变通方法。要使用排序，请设置 DrawObjectsRenderPass.SortingOrder 属性。支持以下排序方式：

  • None - 与未设置该属性相同。

  • BackToFront - 先绘制距离摄像机较远的群集。用于半透明内容。

  • FrontToBack - 先绘制距离摄像机较近的群集。用于不透明内容。

  • Material - 按材质对群集进行分组。用于减少着色器切换。

  之所以使用术语“群集 (Cluster)”，是因为在使用 SortingOrder 时，Kanzi 对渲染条目进行排序，而不是对完整对象进行排序。这意味着，即使 Model3D 的网格包含多个使用不同材质的群集，仍然可以按所使用的着色器可靠地排序。该排序是不稳定的，即无法保证两个排序值相同的群集在各帧之间的确切渲染顺序保持一致。

  这些更改还降低了在 DrawObjectsRenderPass 渲染条目列表中添加和移除节点的开销。

• 创建名称相同但设置冲突的动态属性类型时，不再立即抛出错误。

• 更新了以下第三方库：

  • Zlib 从 1.2.13 到 1.3.2。

  • LibPNG 从 1.6.37 到 1.6.55。

  • FreeType 从 2.12.1 到 2.14.3。FreeType 更新了其内部 TrueType 解释器。这可能会导致文本渲染出现细微差异。

  • HarfBuzz 从 8.3.0 到 13.2.1。此次更新更改了文本整形行为，可能会导致文本布局出现细微差异。

• 开始使用以下第三方库：

  • FlatBuffers 25.12.19-2026-02-06-03fffb2。这为使用任何人都可以编写的公共架构定义 Kanzi 资源提供了基础。

  • yaml-cpp 0.9.0。用于文件格式转换的 Kanzi YAML 解析器和写入器。它将取代 Tiny-XML。

  • Protobuf 3.8.0。用于 Emscripten 平台包中的概念验证工作，以实现更灵活的 KZA 表示形式。

  • Qualcomm Shadow Denoiser 1.0。用于减少光线追踪阴影中的噪点。

• .kzb 文件中的图像数据现在使用 FlatBuffers 消息。目的是让未来的用户能够使用公开的架构向 Kanzi 发送现成的二进制数据块。目前，此更改对用户不可见。

• 在 Android Kanzi 模板中添加了 KANZI_LINK_KZMONITOR CMake 选项。在 build.gradle 中启用该选项以链接 Monitor 插件。有关分步集成说明，请参阅 Kanzi Monitor 文档中的 使用 Gradle、CMake 和 Android Studio 集成到 Android 工程。

Kanzi Engine Lua API

• 现在，您可以使用 DataObject::create 的可选参数来定义数据对象的子树。

• 现在可以使用迭代器 Node2D:iterateChildren 和 Node3D:iterateChildren 遍历节点的子节点。

• 现在，您可以在主循环调度器中注册任务和定时器任务。请参阅 注册主循环调度器任务

• 现在，您可以操作 Node 所拥有的节点组件。

• 现在，您可以在 MessageArgument 子项中对继承的属性使用 getter 和 setter。

• 现在，您可以在 Node 类上使用 InputManipulator 方法。

• Lua 运行时现在分为 Debug 和 Release 版本。Release 版本移除了所有参数验证检查，以牺牲详细的错误消息为代价提高了性能。

• Lua 运行时现在通过直接调度到对应的 C++ 函数来创建对象，而不再通过 Metaclass::createInstance 方法。

渲染 (Rendering)

• 移除了 MappedBuffer 类。现在可以直接通过 kzgfx::mapBuffer 和 kzgfx::unmapBuffer 映射缓冲区。要在不映射的情况下更新缓冲区，可以直接使用 CommandRecorder 或 kzgfx 命令。

• 为 PipelineStateRenderPass 添加了 AlphaToCoverageEnabled 属性，该属性启用 Alpha to Coverage GPU 支持。在渲染使用半透明纹理（如树叶、草或烟雾）的对象或粒子时，请考虑启用此属性，以较低的处理开销获得清晰的抗锯齿边缘。Draw 和 MultiDraw prism 节点中也提供此属性。

• 将 GraphicsColorWriteMode 枚举替换为位掩码标志类型 gfx::ColorWriteMask。现在，您可以使用按位 OR 运算符组合各个通道标志，以控制每个通道的颜色写入。

  请参阅 PipelineStateRenderPass 颜色写入模式的更改。

• 当不需要先前的内容时，Kanzi 现在会使帧缓冲区内容失效，而不是清除帧缓冲区。这可以提高性能，因为无需将帧缓冲区内存复制到图块内存或从图块内存复制出来。

• GPUBuffer 类现在派生自 GPUResource。它现在在整个生命周期内仅管理单个缓冲区句柄，并且不再在内部调整其缓冲区大小。

  因此，Mesh 类和 Geometry 类的 API 也发生了更改。

• RenderState::HandleType 类型现在是强类型枚举，并已重命名为 RenderStateHandle。现在必须将其初始化为 RenderStateHandle::Invalid，而不是 -1。

  RenderStateHandle 现在在句柄的高位中编码 RenderStateDomain。您可以使用 getRenderStateDomain(RenderStateHandle handle) 方便地访问该域。该域可用于确定与此 RenderStateHandle 关联的值是纹理 (Texture)、缓冲区 (Buffer)、Uniform 还是加速结构 (Acceleration Structure)。

• Kanzi 现在要求着色器使用 GLSL ES 310+ 或桌面 GLSL 140+ 源语法。仍支持低至 OpenGL ES 3.0 的部署目标——只要源代码未使用目标版本之后引入的功能，着色器就会被交叉编译为工程的 Target Graphics API 设置所要求的方言。要迁移工程中的着色器，请参阅 对着色器编译的更改。

• 新工程的默认 Target Graphics API 现在为 OpenGL ES 3.1。现有工程保留其当前设置。

• 添加了对 Volume Texture 的支持。

  请参阅 使用体积纹理。

• 添加了对 Buffer 对象的支持。

• 添加了对 Compute 渲染通道的支持。

• 添加了对 Basis Universal 纹理压缩的支持。支持的纹理模式：UASTC LDR、UASTC HDR 4x4、UASTC HDR 6x6 和 ETC1S。

• 改进了 Kanzi Studio 预览中的 3D Grid 可视化效果。网格现在以单位为基础，更易于阅读，也更便于在 3D 空间中放置对象时用作参考。

  

• 更改了 RenderPass::CameraSettings::initializeFromLight，以支持自动拟合方向阴影投影。

• 添加了对 速度缓冲区生成 的支持。现在您可以在材质中输出逐像素的屏幕空间速度，这是运动模糊和时间抗锯齿 (TAA) 等效果的基础。

  此功能引入了： - 用于基于物理的渲染材质的新预处理器定义 KANZI_SHADER_OUTPUT_VELOCITY 和 KANZI_SHADER_OUTPUT_VELOCITY_INDEX。 - 新的固定 Uniform kzPreviousProjectionCameraWorldMatrix，用于提供上一帧的投影-摄像机-世界矩阵以计算速度。

• 重构了 Mesh::CreateInfo 及相关 API：

  • 顶点源数据现在按特性去交错。移除了 Mesh::CreateInfo::vertexData 和 vertexBufferHandle；每个 MeshVertexAttribute 都带有各自的 initialData 字节和可选的 bufferHandle。

  • 已创建的 Mesh 上的顶点缓冲区现在通过 Mesh::getVertexBuffer 按特性公开。容器类型为 Mesh::VertexBufferContainer。

  • MeshVertexAttribute::dataType 和 dimension 已合并为单个 gfx::Format 字段。新的 gfx::ChannelType 变体 UNorm、SNorm 和 UFloat 可提供准确的格式分类。移除了 MeshVertexAttribute::stride；请改为通过 gfx::getPixelStride 推导。

  • 添加了结构化的 Mesh::CreateInfo 验证：validateCreateInfo、getVerboseDescription 和 Mesh::CreateInfo::Status 枚举。

  • adjustForDeviceCapabilities 现在返回描述所做调整的 vector<Mesh::CreateInfo::Adjustment> （之前为 void）。

  • 管线验证现在将 UNorm/SNorm/UFloat 通道类型视为与着色器 float 输入、ColorRGBA 清除值和 ColorRGBA 采样器边框颜色兼容。之前这些组合会被拒绝。

  请参阅 Mesh::CreateInfo 和顶点辅助 API 的更改。

• gfx::DepthAttachmentDescription 新增了 isDepthReadOnly 和 isStencilReadOnly 字段。将其中任一字段设置为 true，即可声明渲染通道不会修改其深度/模板附件的相应方面，从而允许同一深度（或模板）纹理在仍绑定为帧缓冲区深度/模板附件的同时作为输入被采样。在打包的深度/模板格式上使用非对称组合需要新的 gfx::FeatureId::SeparateDepthStencilLayouts （Vulkan 1.2 / VK_KHR_separate_depth_stencil_layouts；在 OpenGL 上始终可用）。如果该功能不可用，渲染通道验证会报告 create-renderpass-separate-depth-stencil-layouts。在命令流处理时，如果绑定的深度/模板状态会修改只读方面，只读通道内的 BeginRenderPipelineCommand 会报告 commands-begin-render-pipeline-depth-write-in-read-only-pass 或 commands-begin-render-pipeline-stencil-write-in-read-only-pass。这两个字段的默认值均为 false；现有管线不受影响。此外，CompositionTargetRenderPass 在重用外部提供的深度目标时不再使帧缓冲区失效。

• 重构了网格顶点缓冲区，使其去交错，从而可以在单个缓冲区中单独访问每个特性。因此，以下 Mesh 类方法现在需要一个用于访问特定特性的参数：Mesh::getVertexBufferHandle、Mesh::getVertexBuffer、Mesh::setVertexData、Mesh::setVertexSubData。

  请参阅 Renderer API 的更改。

• 着色器反射现在会公开每个输入和输出特性上的 location 和 component 限定符。gfx::reflection::ReflectionInfo::inputAttributes 和 outputAttributes 现在将特性名称映射到新的 gfx::reflection::Attribute 结构体，该结构体包含 location、component 以及现有的 typeInfo。这使编译后的着色器成为片段输出写入哪个颜色附件的哪些通道的唯一事实来源，包括 layout(location = 1, component = 2) out float 等带有 component 限定的布局——这对于将多个标量输出打包到单个渲染目标中的通道非常有用。

  渲染管线验证使用新的反射字段，将每个已绑定颜色附件的混合状态写入掩码与反射的输出、已绑定附件的通道集以及当前渲染通道进行核对。该检查在处理 BeginRenderPipelineCommand 时运行——这是验证器唯一能够看到实际附件格式的时间点——当混合状态启用了对某个通道的写入，而该通道片段着色器不生成 且 已绑定附件包含时，会报告 commands-color-write-mask-mismatch。针对已绑定附件所不具备的通道的写入掩码位在硬件上不起作用，不会发出警告。location 超出已绑定附件数量的片段输出也不会被检查——多余的写入会被丢弃，因此单个着色器可以驱动数量可变的已绑定附件。

• 添加了用于去交错网格缓冲区的绑定表达式访问器。现在您可以直接在绑定表达式中读取 Mesh 的逐特性 GPU 缓冲区和计数：meshGetPositionBuffer、meshGetNormalBuffer、meshGetTangentBuffer、meshGetUVBuffer、meshGetIndexBuffer、meshGetVertexCount 和 meshGetIndexCount。这样，您无需编写 C++ 代码即可实现诸如将网格的顶点缓冲区作为存储缓冲区绑定到 Compute Render Pass，或者根据顶点或索引计数决定调度大小等操作。

  请参阅 网格函数。

• 将输出视口属性从 kanzi::DrawObjectsRenderPass 移至 RenderPass 基类，并将其重命名为 RenderPass::OutputViewportProperty，以明确该属性报告的是渲染通道生成的视口区域。现在每个渲染通道都公开该属性，而不仅限于 Draw Objects 渲染通道。

  请参阅 Renderer API 的更改。

• 改进了 Render Target Texture 和 Cubemap Render Target Texture 的 Depth / Stencil Attachment 属性：

  • 启用了 Depth 32-bit, Stencil 8-bit (D32_SFLOAT_S8_UINT) 格式。当您需要组合的 32 位浮点深度和 8 位模板附件时，请使用此格式。

  • 将默认格式更改为 Depth 32-bit (D32_SFLOAT)，以获得更高的深度精度。

  • 添加了在 GPU 不支持所选格式时使用最接近的受支持格式作为后备的支持。

• 移除了 GraphicsLoggingEnabled 应用程序配置选项、对应的 --log-graphics 命令行选项以及公开的 kanzi::Renderer::setLogging API。自 OpenGL/Vulkan 渲染器重构以来，该选项一直不起作用；图形 API 调用日志的重新实现由 RENDERING-2703 单独跟踪。

• 移除了 kanzi::Renderer::getLogging 和 kanzi::Renderer::getDumpStateOnDrawCalls。在移除 kanzi::Renderer::setLogging 之后，这些 getter 已没有对应的 setter，因此无法通过任何公开 API 更改其返回值。

  Kanzi 4.1.0 包含图形信息日志功能，即在启动时一次性报告图形后端、设备、版本、扩展和格式支持情况，由 LogOpenGLInformation、LogOpenGLExtensions 和 LogSurfaceInformation 应用程序配置选项控制。它不包含图形 API 调用日志（带状态转储的逐绘制调用跟踪），该功能在 Kanzi 3.9 中可用，并计划在未来的版本中恢复。

• 添加了 Bindless Raytracing Advanced 示例，演示如何在 3D 场景中使用无绑定渲染实现光线追踪阴影和反射。该示例包含一个自定义渲染通道预设件，其中含有 Build Acceleration Structure、Raytraced Shadows 和 Raytraced Reflections 通道。

  请参阅 Bindless Raytracing Advanced 示例。

• 添加了实验性的光线追踪支持。需要将 Vulkan 1.2 或更高版本作为目标图形 API。

  备注

  光线追踪为 实验性 功能。该 API 可能会在未来版本中更改。

  提供以下渲染通道：

  • BuildAccelerationStructureRenderPass — 每帧根据场景几何体构建顶层加速结构。

  • RaytracedShadowRenderPass — 追踪光线，为所选灯光生成屏幕空间阴影遮罩。

  • RaytracedReflectionRenderPass — 追踪光线，为粗糙度低于可配置阈值的表面计算逐像素反射。

  • DenoiserRenderPass — 在合成之前对阴影遮罩应用时间降噪。

  有关完整的可运行示例，请参阅 Bindless Raytracing Advanced 示例 示例工程。

• 新增实验性的无绑定 (bindless) 支持。需要使用 Vulkan 1.2 或更高版本作为目标图形 API。

  备注

  无绑定纹理支持为 实验性 功能。该 API 可能会在未来版本中更改。

  引入了以下类：

  • BindlessTextureRegistry 管理 2D 纹理的无绑定描述符数组。纹理采用引用计数——多次注册同一纹理是安全的。着色器通过整数索引访问纹理，而不是通过单独的描述符绑定。

  选择使用无绑定的着色器还可以访问以下驻留在 GPU 上的场景数据，这些数据通过 kzGPUScene Uniform 块公开：

  • kzGPUSceneMeshInfo——每个网格的位置、法线、切线、UV 和索引的缓冲区设备地址。

  • kzGPUSceneInstanceInfo——每个群集实例的变换矩阵，以及指向网格表和材质表的索引。

  • kzGPUSceneMaterialInfo——每个材质的属性值。此结构体由 用户定义：您需要在共享的 GLSL 头文件中声明该结构体，并在参与无绑定场景的每个着色器中包含该头文件。引擎使用反射发现其布局，并据此打包材质数据。场景中的所有着色器都必须声明相同的 kzGPUSceneMaterialInfo 结构体。

  • kzGPUSceneMaterialIndex——由引擎为每次绘制设置的 Uniform，用于在材质缓冲区中进行索引，以获取当前渲染群集的 kzGPUSceneMaterialInfo。

  这些结构共同使完整的场景几何体和材质数据可用于任何着色器阶段，从而实现诸如使用 Alpha 测试材质的 GBuffer 渲染，以及需要在光线命中时为任意网格和材质解析命中表面属性的光线追踪反射等效果。

  有关完整的可运行示例，请参阅 Bindless Raytracing Advanced 示例 示例工程。

应用程序框架

• 在 Kanzi 应用程序框架 (appfw) 中新增 setTracingOutputDirectory 函数，用于在 Android 上设置跟踪文件的输出目录。

• 新增 DomainController 基类和 Domain::getController 访问器。Application 派生自 DomainController，因此持有 Domain 指针的插件可以通过 domain->getController<MyApplication>() 访问真正特定于宿主的状态（即宿主子类上由客户定义的方法和字段），而无需让 Domain 依赖 Application。请将此机制用于存在于宿主上的状态；插件对场景图及其他由 Domain 拥有的功能的访问，应通过相应的 Domain 访问器进行。不派生自 Application 的宿主可以直接派生自 DomainController，以通过相同机制向插件公开其宿主实例。

  将 DomainController 添加为 Application 的基类会改变后者的虚函数表和对象布局，因此基于 Kanzi 4.1.0 头文件构建的树外插件和应用程序必须重新构建。

• 新增一组 Domain 访问器，使 Engine 插件能够通过注册时收到的 Domain 指针直接访问由 Application 拥有的功能，而无需依赖 Application：

  • Domain::getScreens——宿主的 Screen 节点。单屏幕应用程序返回其 Screen 作为唯一元素。在 Android 上，应用程序框架返回其所有视图的 Screen，因此基于此访问器编写的插件无需特定于宿主的代码即可在多窗口应用程序中工作。

  • Domain::getApplicationProperties——应用程序属性。

  • Domain::getPerformanceInfoLevel 和 Domain::setPerformanceInfoLevel——性能 HUD 档位。

  • Domain::getRenderingAreaOffset — 渲染区域偏移。

  • Domain::getRootCompositionTarget — 根合成目标。

  • Domain::getStartupProfilerRegistry——启动剖析程序注册表。

  • Domain::getState 和 Domain::getFramesPerSecond——主循环状态和帧率。

  当宿主不提供相应功能时，每个访问器都会返回空值或默认值。请在使用前检查返回结果。

模板

• 使用 C++ 代码的应用程序模板现在包含 iOS 平台配置。当您使用 Application、Application with data source plugin 或 Application with Kanzi Engine plugin 模板创建工程时，Kanzi Studio 会生成现成的 iOS CMake 配置以及用于生成 Xcode 工程的辅助脚本。

  请参阅 为 iOS 开发 Kanzi 应用程序。

• 移除了 Conan 风格的 Studio 应用程序模板。

平台

• Kanzi 现在会在创建 Wayland 图形输出时调用 setAppId()。

• KZ_LOG_CATEGORY_EGL 现在包含有关平台级功能支持的诊断警告，并且默认启用。

• 移除了 listEGLAttributes，改用更灵活的 formatEGLAttributes，后者会创建格式化的、易于阅读的字符串。

  请参阅 平台的更改

• Platform 类已重命名为 platform::PlatformContext。所有派生类也已相应重命名。

  请参阅 平台的更改

• GlContextApi 类已重命名为 platform::GlGraphicsContext。所有派生类也已相应重命名。

  请参阅 平台的更改

• platform::GlGraphicsContext 的成员函数 getOGLProcAddress 已重命名为 getGLProcAddress。该类还新增了 getGLProcAddressInto 辅助函数，它将带类型的 OpenGL 入口点加载到传入的函数指针中，并报告是否找到了该入口点。

  请参阅 运行时 (Runtime) API 的更改

• kzplatform 库的内部文件夹结构已更改，导致许多文件被移动。

  请参阅 运行时 (Runtime) API 的更改

• 将 platform::createDefaultPlatformContext、platform::destroyDefaultPlatformContext 和 platform::getDefaultPlatformContext 从 platform_context.hpp 移至专用的 default_platform_context.hpp 头文件。

  请参阅 平台的更改

iOS

• Kanzi for iOS 现在在视图级别进行集成，因此您可以在任何 iOS 应用程序中将 Kanzi 内容与原生视图一起嵌入。在 UIKit 应用程序中使用 KanziView，在 SwiftUI 应用程序中使用 KanziViewRepresentable。

  请参阅 为 iOS 开发 Kanzi 应用程序。

• Kanzi 应用程序模板现在附带一个承载 KanziView 的 iOS 应用程序外壳。使用 Application、Application with data source plugin 和 Application with Kanzi Engine plugin 模板创建的工程无需修改即可针对 iOS 构建：生成的 configs/platforms/ios/src/ 目录包含 UIApplicationMain 入口点、应用和场景委托，以及一个承载 KanziView 的 UIViewController。

  请参阅 为 iOS 开发 Kanzi 应用程序。

Android

• 将 Android NDK 版本更新为 28.2.13676358。Kanzi 现在默认支持 16 KB 页面大小，这是 Android 15 及更高版本设备上 Google Play 兼容性 的要求。请参阅 对 Android NDK 版本的更改

• 更新了 Android 示例和教程以匹配最新模板，从而支持 JDK 21。

• 现在，当所选工作区路径包含空格时，Kanzi 安装程序会发出警告。Android Gradle Plugin 无法从包含空格的工作区路径打包原生共享库。

• getkanzi.gradle 现在会记录用于解析 Kanzi 工作区的来源（local.properties、Gradle 属性、KANZI_HOME 环境变量或父目录搜索）以及解析得到的路径。这样可以更方便地诊断 Android 构建过程中的工作区解析问题。请参阅 将 Kanzi 作为库子项目集成

Package Manager

• 引入了 Kanzi Package Manager，用于共享和管理可复用软件组件及资产，并支持跨平台应用程序和插件开发。您可以使用它安装、更新和移除工程依赖项。

  请参阅 Package Manager。

Kanzi 安装程序

• Kanzi 安装程序现在会将 Package Manager 作为可选的安装后步骤进行安装。请参阅 安装 Kanzi Package Manager。

Kanzi Android Service

• 引入了 Kanzi Android Service 框架，使您能够在多个 Android 应用程序之间使用同一个 Kanzi 实例和资源。此外，这还可以在共享 Kanzi 内容的应用程序之间实现无缝过渡。

  

  请参阅 使用 Kanzi Android Service 进行开发。

Kanzi Studio 插件

• Kanzi Studio 现在支持对带有依赖 DLL 的插件进行基于清单的插件发现。将所有插件文件放在 plugins 目录下的子目录中，并添加一个声明入口点 DLL 的 <PluginName>.manifest.json 文件。Kanzi Studio 仅加载所声明的入口点 DLL，并从同一目录解析其他依赖项。

• Kanzi Studio 现在支持插件热重载。当 Kanzi Studio 运行时，如果您在 plugins 目录中添加、更新或移除插件文件，Kanzi Studio 会自动检测这些更改并重新加载插件，无需重新启动。当您移除插件时，Kanzi Studio 会关闭所有已打开的插件窗口并清理相关的菜单项。

请参阅 安装 Kanzi Studio 插件。

Kanzi Studio 插件 API

• Kanzi Studio 插件 API 现在公开了 KanziStudio.GetPreviewScreenshot，它会捕获当前的 Preview 帧，并以 PNG 编码的字节数组形式返回。

• 添加了 Project.CreateLightNode，它会创建指定类型（Directional Light、Point Light 或 Spot Light）的 Light 节点。

• 添加了 Commands.ImportImages 的非交互式重载，它接受显式的 HDR 导入设置（2D 纹理、环境 cubemap、IBL cubemaps、分辨率和采样数）。

Kanzi Studio 可用性

• Kanzi Studio 现在仅将 kzm 格式版本写入根 kzm 文件。只能在来自同一 Kanzi Studio 版本的工程之间复制 kzm 文件。请参阅 复制 kzm 文件

• Kanzi Studio 现在可以将工程项导出为可共享的归档文件，并将其导入到工程中。请参阅 导出和导入工程项

• Kanzi Studio 不再支持保存材质类型 (.kzmat)，并且从磁盘加载材质类型已被弃用。请改用导出和导入工程项。请参阅 导出和导入工程项

• Kanzi Studio 现在从 <KanziInstallation>/Studio/Asset Library/MaterialTypes 工程导入默认材质，而不再从 .kzmat 文件导入。

• Kanzi Studio 现在会保留手动添加到工程目录中的 kzm 文件和文件夹，即使它们未连接到工程层级结构。这样，您可以通过复制文件在工程之间复用工程项，并支持自定义文件夹组织方式，而不会出现文件被意外删除的情况。

• 当 Kanzi Studio 检测到工程目录中的 .kzm 文件在 Kanzi Studio 之外被更改时，除了现有的重新加载选项外，现在还提供将磁盘上的更改合并到您未保存的本地更改中的选项。请参阅 响应 kzm 文件更改。

• 当多个工程在 Kanzi Studio 之外被修改时，Kanzi Studio 现在只显示一个对话框窗口，提示您对所有这些工程的更改执行 Reload、Merge 或 Ignore。

• Kanzi Studio 不再在 .kzm 文件中序列化工程项的创建时间戳。Item Details 对话框和 Find 对话框现在显示 Last modified 值，而不是之前的 Created 字段，该值取自包含该项的 .kzm 文件的最后修改时间。打开和保存工程时不再重写 .kzm 文件中的这些时间戳。

• 现在，您可以在 Kanzi Studio 脚本中使用 ImportAsset3DSourceFile 命令导入 3D 资产。

• Kanzi Studio 现在会记录部分用户可感知操作的性能测量数据，并将其写入 Kanzi Studio 日志文件。被检测的操作包括打开工程、创建工程、保存工程、kzb 导出和启动 Preview。每个操作会生成一行带有 [PROFILE] 标记的日志，其中包含操作名称、以毫秒为单位的持续时间，以及工程路径或输出大小等元数据。

  剖析功能默认处于关闭状态。要启用该功能，请选择 Edit > User Preferences > Advanced > Profiling，然后选中 Enable profiling。该设置会在 Kanzi Studio 会话之间保留。剖析输出显示在 Kanzi Studio 日志 %TEMP%\KanziStudioLogs\KanziStudio.log 中。

• 启用缩略图渲染时，Kanzi Studio Preview 的帧率不再下降。

Prism 图编辑器

• Prism 图编辑器现在会在您编辑时验证连接。编辑器会高亮显示无效连接，并在 tooltip 中显示问题。

  

• 在 Prism Editor 中，更改 Blit 节点上所选的 Blit Material 属性时，现在会移除与之前所选材质关联的所有属性。

• 当您将鼠标悬停在有效连接上时，Prism 图编辑器现在会显示详细的帧缓冲区信息。tooltip 会显示流经该连接的数据的 aspect、格式和分辨率。

  

• 添加了新的 Prism 节点类型：

  • Chromatic Aberration

  • Color Grading

  • Vignette

• Generate Shadowmap 节点新增了用于配置方向投影的属性。

• Prism 节点上的材质属性现在提供 Override value from Viewport 按钮，使用该 Prism 图的每个 Viewport 都可以通过它独立覆盖该属性值。

  

• 重命名了 Color Grading Prism 节点属性的显示名称，以避免与 Shadow Effect 2D 节点属性冲突：

  旧名称	新名称
  Highlight Color	Grading Color Highlight
  Highlight Range	Grading Highlight Range
  Midtone Color	Grading Color Midtone
  Shadow Color	Grading Color Shadow
  Shadow Range	Grading Shadow Range
  Hue Saturation Value	Grading Hue Saturation Value

• Prism 图编辑器现在支持 渲染通道 (Render Pass) 节点。您可以将引擎渲染通道类型（例如 Build Acceleration Structure 渲染通道和 Compute 渲染通道）直接添加到 Prism 图中。每个渲染通道节点都会公开其引擎属性，供您在 Prism 编辑器中编辑。

  

• Prism 图编辑器现在支持在渲染通道节点之间使用 资源属性绑定。从一个渲染通道节点上的资源输出属性拖出一条绑定线，连接到另一个渲染通道节点上相同类型的资源属性，即可复制该值。

  

  有关完整示例，请参阅 绑定 Render Pass 节点属性。

• Prism 图编辑器现在支持在渲染通道节点的非资源属性上使用 文本属性绑定。右键单击渲染通道节点上的任意数字、布尔值、颜色或其他非资源属性，然后选择 Edit binding…，即可通过绑定表达式驱动该属性的值。属性行会在标签上显示绑定指示器，并显示表达式的只读预览。要移除绑定，请右键单击并选择 Clear binding。

  有关完整示例，请参阅 绑定 Render Pass 节点属性。

着色器图编辑器（实验性）

• 引入了 Shader Graph Editor，这是一个用于构建 GLSL 片段着色器的实验性可视化节点编辑器。您可以创建着色器图、连接节点并生成着色器代码，而无需手动编写 GLSL。要启用该编辑器，请转到 Edit > User Preferences > Experimental 选项卡 > Web-based editors，然后启用 Shader Graph Editor。

  

  请参阅 着色器图（实验性）。

Flags 属性

• 引入了新的 Flags 属性类型，用于定义带有命名位字段的位掩码属性。在 New Property Type 窗口中，选择 Flags 作为数据类型。该属性存储一个整数位掩码，其中每一位都有各自的名称。

  

  请参阅 valueProvider。

Kanzi Engine C++ API

• 添加了 Node::lookupNodeRaw 的 const 版本。

• 更改了任务调度程序 API。TaskDispatcherBase 现已合并到 TaskDispatcher 中，并且头文件位置已更改。

  请参阅 运行时 (Runtime) API 的更改

• 重命名了 TextBoxConcept 中消息参数的元类。请参阅 TextBoxConcept API 的更改。

• 重命名了 TextInputManipulator 中消息参数的元类。请参阅 TextInputManipulator API 的更改。

• 添加了 NodeComponent::supportsStateTransition 和 NodeComponent::transitionFrom 虚函数。在自定义节点组件中重写这些函数，即可参与状态机的交叉淡化协议，并在状态机切换状态时执行自驱动的过渡。

• 重构了 MainLoopScheduler，使其更好地遵循 C++ 编码规范。此次重构无需进行迁移。

• 添加了一个辅助工具，用于提取插件提供的元类，而无需将插件注册到 Domain 中。<kanzi/core/module/plugin_metadata_extractor.hpp> 中新增的公共 API 包括：

  • collectPluginMetaclasses — 给定一个 Module 引用和一组引擎拥有的基准元类，返回该模块通过 Module::getMetaclassesOverride 提供的元类，以及这些元类在插件内的传递闭包：嵌套元类、消息参数元类、插件定义的基类（命名的和未命名的）以及插件定义的 mixin 元类。即使插件只列出其叶元类，也仍会得到这些叶元类所派生的插件定义基类和 mixin 的元数据。引擎拥有的元类（即所提供的基准集中的元类）在格式化输出中按名称引用，不会添加到返回的 vector 中。

  • LoadedPlugin — 一个仅可移动的 RAII 句柄，同时拥有由插件的 createModule 入口点生成的 Module 以及生成该模块的共享库句柄。析构函数会先销毁模块再关闭库，因此位于库中的模块 vtable 在模块的整个生命周期内始终有效。

  • loadPluginForMetadata — 打开插件共享库，调用其 createModule 入口点，并返回已填充的 LoadedPlugin。该函数不会将模块注册到 Domain 中，也不会调用 Module::registerMetadataOverride，因此在该钩子中执行设置的插件在提取元数据期间无需承担其开销。

  从工具中提取插件元数据时，请使用此辅助工具，而不是将插件注册到 Domain 中再对比 ObjectFactory 的差异。配套的 plugin_metadata_reader 使用方在原生插件（.dll / .so）路径中使用了该工具。

动画 (Animations)

• 当 State Manager 在各自配置了同名 Animation Player 的状态之间切换时，Animation Player 现在会平滑地交叉淡化。退出的动画和进入的动画会在配置的过渡持续时间内混合，而不是突然切换。

  请参阅 在状态之间交叉淡化动画。

着色器 (Shaders)

• 添加了着色器 include 库，即 Kanzi Studio 随附安装的一组可重用 .glsl 文件。您可以在任何工程着色器中使用 #include 指令包含系统着色器文件，而无需将其复制到工程目录中。要为您的工程自定义系统着色器，请从 Library > Resource Files > System Shaders 中克隆该着色器。

  请参阅 使用着色器包含库。

文档 (Documentation)

• 添加了 将工程从 Kanzi 3.9 迁移到 Kanzi 4 页面，介绍如何将 Kanzi 3.9 工程迁移到 Kanzi 4 模板结构，内容涵盖 CMake 更改、Kanzi 解析器、工程文件转换、着色器迁移以及 Android Gradle 更改。

• 添加了 使用 Kanzi AI 工具 章节，其中包含 Kanzi API MCP 服务器和 Kanzi 文档 MCP 服务器的文档。使用这些服务器可将您的 AI 助手连接到 Kanzi API 参考和用户文档。

• 将 Kanzi 文档 MCP 服务器更新为位于 https://docs.mcp.kanzi.com 的统一端点，该端点支持所有已加载的 Kanzi 版本。用于 Claude Desktop 的 mcpb 文件现在可从 https://docs.kanzi.com/mcp/kanzi-docs-mcp.zip 获取。请参阅 Kanzi 文档 MCP 服务器。

• 全面改进了 docs.kanzi.com Documentation 网站上的搜索和 AI 助手体验，让您能更快地找到所需内容，并获得更准确、有据可依的信息。现在，搜索会返回整个 Kanzi 文档中的结果，包括 Kanzi 框架、功能包和工具。您现在可以将搜索范围缩小到特定的文档集或 Kanzi 版本。新的 Ask Kanzi AI 助手基于同一套文档和 API 参考回答您的问题，并将您正在阅读的页面（以及您选定的任何文本）用作后续提问的上下文。有关如何使用搜索的详细信息，请参阅 搜索 Documentation。

• 添加了 Package Manager 章节，介绍 Kanzi Package Manager (KPM)：如何安装、如何使用 Kanzi Studio 插件，以及如何将资产包和 Kanzi Engine 插件创建并部署为 Conan 包。

显著修复

Kanzi Engine

• 修复了以下问题：在脚本中添加的 Lua 消息处理程序会一直保留在 Kanzi Preview 中，直到重新启动 Preview 为止，即使更新或移除了该处理程序也是如此。(ANDROID-1469)

• 修复了以下问题：如果在资源加载期间抛出异常，资源管理器中的异步加载任务可能无法完成，导致 Kanzi 在关闭时无限期挂起。(FMW-890)

• 修复了以下问题：使用固定宽度渲染的文本节点错误地将固定字符宽度应用于变音符号和其他组合标记，导致文本渲染错位。(FMW-239)

• 修复了以下问题：在具有固定字符宽度的 TextBox 节点中，光标位置和选择高亮未与固定宽度字符槽的边界对齐。(FMW-243)

• 修复了以下问题：当列表滚动到靠近末尾的项目时，如果数据源批量替换了其项目，3D 轨迹列表框 (Trajectory List Box 3D) 会崩溃。(FMW-988)

Kanzi Studio

• 修复了使用外侧节点手柄 在预览中难以旋转已选定 3D 节点的问题。(EDITORS-355)

• 修复了 Kanzi Studio Library 面板中上下文菜单的错误行为。(EDITORS-552)

• 修复了在 Prism 图形编辑器中复制 Blit 节点时无法复制属性值的问题。(EDITORS-551)

• 修复了 Kanzi Studio 中导致 kzm 文件中序列化的 double 类型丢失精度的问题。(FMW-883)

• 修复了复制节点后移除连接时，Prism 图形编辑器中的节点连接器未被清除的问题。(EDITORS-557)

• 修复了在某些计算机上导致 Kanzi Studio 启动时崩溃的问题。(EDITORS-238)

• 修复了 Kanzi Studio 中导致无法编辑显示名称相同的绑定的问题。(FMW-963)

• 修复了网格的群集材质包含无效引用时导致 Kanzi Studio 终止的问题。(FMW-959)

• 修复了 Kanzi Studio 中在屏幕边缘显示 tooltip 时阻止选择菜单项的问题。(EDITORS-82)

• 修复了在节点树中将不同类型的资源包拖放到彼此相邻位置时，导致 Kanzi Studio 替换节点而不是添加节点的问题。(EDITORS-120)

• 修复了允许 Kanzi Studio 脚本的子命令异步运行的问题。(FMW-1012)

• 修复了导致 Kanzi Studio 导入带有过时绑定的材质的问题。(FMW-1028)

• 修复了在绑定覆盖上下文菜单中选择别名绑定时，导致 Kanzi Studio 因异常而终止的问题。(EDITORS-737)

• 修复了视口使用自定义渲染通道预设件时，Kanzi Studio Preview 中不显示选择轮廓的问题。(EDITORS-788)

• 修复了 Kanzi Studio 中编辑、禁用或移除同一节点上两个重复绑定中的一个时，另一个也受到影响的问题。(FMW-1103)

• 修复了 Kanzi Studio 在不显示交互式 HDR 导入对话框的情况下（例如从插件或脚本）导入 HDR 图像时，HDR cubemap 生成可能失败的问题。(EDITORS-912)

• 修复了从版本控制克隆工程或导入资源包后，基于图像的光照 cubemap 所生成的面和粗糙度 mipmap 可能丢失，从而导致基于物理的渲染不正确的问题。生成的内容被排除在版本控制之外，也不会打包到资源包中，因此以前无法恢复：运行时会回退为使用盒式滤波的 mipmap，而这种 mipmap 对于基于图像的光照是不正确的；对于 ASTC 或 Basis 等压缩纹理，运行时则根本无法生成 mipmap。

  Kanzi Studio 现在会记录每个基于图像的光照 cubemap 的生成方式，包括其类型、分辨率和采样数，并保留对源图像的引用。当生成的面或粗糙度 mipmap 缺失时，Kanzi Studio 会在加载工程和导入资源包时根据源图像重新创建它们。仅当生成的内容缺失时才会执行重新生成，因此打开完整的工程不会修改该工程。

  由于重新生成依赖于源图像，您必须在工程中保留用于生成每个基于图像的光照 cubemap 的源 HDR 图像。如果移除源图像，则无法再重新生成该 cubemap。在此更改之前创建的 cubemap 不带有生成记录，必须重新创建并重新打包，以便源图像及其生成设置随工程一起传递。(FMW-1117)

Kanzi Java API

• 修复了在代码中动态创建 Kanzi 对象时 Kanzi Java API 内存占用无限增长的问题。(ANDROID-1674)

• 修复了通过 Node::addTunnelingMessageHandler 方法注册消息处理程序导致的内存泄漏。

• 修复了创建 Kanzi 原生类的对象时发生的内存泄漏。

渲染 (Rendering)

• 修复了使用 Composition Target 渲染通道进行视口渲染时，调试可视化渲染不正确的问题。当使用 Blit 渲染通道渲染场景时，当前实现仍存在与缺少深度纹理相关的限制。(RENDERING-2368)

• 修复了在片段着色器中未使用所需扩展的情况下使用高级混合模式时，在某些 GPU 上导致渲染问题和崩溃的问题。(RENDERING-2271)

另请参阅

Kanzi 4.1.0 迁移指南

已知问题