Kanzi 4.1.0 迁移指南¶

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

工程和插件模板结构的更改¶

如果您要从 Kanzi 3.9 迁移到 Kanzi 4.1.0，请注意工程和插件模板结构在 Kanzi 3.9 和 Kanzi 4 之间发生了重大变化。应用本指南中的 API 更改时，外围的构建结构（CMake 文件、构建脚本、平台配置和插件构建设置）不会自动迁移。有关迁移构建结构的分步指南，请参阅将工程从 Kanzi 3.9 迁移到 Kanzi 4。

属性类型的更改¶

创建名称相同但设置冲突的动态属性类型时，不再立即抛出错误。Kanzi Engine 会首先尝试通过保留最初的动态属性类型的设置来进行恢复。新创建的属性类型将被丢弃。

在以下情况下无法恢复： - 新创建的 PropertyType 与已有的同名属性类型的数据类型不同。 - 您在代码中使用静态 PropertyType<DataType> 对象创建属性类型。

这些情况仍会抛出错误。该恢复机制适用于从 .kzb 文件加载的属性类型。

每个不一致之处都会作为警告记录在日志中。

与属性类型相关的更改还会带来以下其他影响：

AbstractRange 接口现在有一个新函数 virtual bool equalsOverride(const AbstractRange& other) const，继承该接口的范围必须实现此函数。

如果用户声明了要与 TypedValueRange<T> 一起使用的新类型，则必须为该类型实现 template <> kanzi::detail::propertyDataValueEquals(const T&, const T&)。
现在，每个基本 Kanzi 数据类型在 kanzi:: 命名空间中都有一个对应的 to_string() 函数。

构建系统的更改¶

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

在 Android 工程中，我们建议将 Gradle 使用的 CMake 版本设置为 3.30.5，因为这是 Android SDK 提供的最低兼容版本。或者，您可以将自定义的 CMake 添加到 PATH 环境变量中。要在 Gradle 中指定 CMake 版本，请按如下方式更新 Application/configs/platforms/android_gradle/kanzinative/build.gradle 文件：
```
android {
  externalNativeBuild {
    cmake {
      ---------------
      version '3.30.5'
    }
  }
}
```
KANZI_ROOT CMake 变量已重命名为 Kanzi_ROOT，以符合 CMake 策略 CMP0144 的要求，该策略要求 <PackageName>_ROOT 提示变量的大小写与 find_package() 调用中使用的大小写一致。

如果您在 CMake 命令行中传递 -DKANZI_ROOT=<path>、在环境中设置 KANZI_ROOT，或者在 CMakeLists.txt 中引用 KANZI_ROOT，请将其重命名为 Kanzi_ROOT：

Kanzi 4.0

Kanzi 4.1

-DKANZI_ROOT=<path>

-DKanzi_ROOT=<path>

set(KANZI_ROOT <path>)

set(Kanzi_ROOT <path>)

$ENV{KANZI_ROOT}

$ENV{Kanzi_ROOT}

Kanzi 4.0	Kanzi 4.1
`-DKANZI_ROOT=<path>`	`-DKanzi_ROOT=<path>`
`set(KANZI_ROOT <path>)`	`set(Kanzi_ROOT <path>)`
`$ENV{KANZI_ROOT}`	`$ENV{Kanzi_ROOT}`

Renderer API 的更改¶

GPUBuffer 现在派生自 GPUResource，并且可以用作资源属性类型中的属性值。

GPUResource 中移除了许多函数，特别是 setData() 和 setSubData()。要更新 GPUResource 在 GPU 端的内容，请使用 gfx 命令，通过句柄映射缓冲区，或者分配暂存缓冲区并复制该缓冲区。也可以使用 kanzi::CommandRecorder::updateBuffer()。

另外还新增了 updateGPUBufferData，可用于轻松更新缓冲区。它在内部调用 kanzi::CommandRecorder::updateBuffer()。

另外还新增了 setGPUBufferData，可用于轻松地以全新数据更新 GPUBuffer，而无论之前缓冲区的大小如何。它在内部使用 CommandRecorder 更新缓冲区内容。
RenderState::HandleType 现在为 RenderStateHandle。其 invalid 状态不再是 -1。请改用 RenderStateHandle::Invalid。
RenderPass::CameraSettings::initializeFromLight 函数签名已更改。

移除了 Renderer 引用，并添加了 RenderPass 引用，以支持自动拟合方向阴影投影。
kanzi::BindingRenderValueLookupContext 已重命名为 BindingGraphicsEntryLookupContext。

Kanzi 4.0

Kanzi 4.1

BindingRenderValueLookupContext

BindingGraphicsEntryLookupContext

Kanzi 4.0	Kanzi 4.1
`BindingRenderValueLookupContext`	`BindingGraphicsEntryLookupContext`

Mesh::CreateInfo 和顶点辅助 API 的更改¶

Mesh::CreateInfo 已重新设计，顶点数据现在按特性 (Attribute) 分别持有，而不再是单个交错数据块。移除了若干自由辅助函数和一个 Mesh 访问器。

已移除 Mesh::CreateInfo::vertexData 和 Mesh::CreateInfo::vertexBufferHandle。源顶点数据和任何预先创建的缓冲区句柄现在作为 initialData 和 bufferHandle 字段位于每个 MeshVertexAttribute 上。

// Before
Mesh::CreateInfo createInfo;
createInfo.vertexData = ...;          // single interleaved blob
createInfo.vertexBufferHandle = ...;

// After — set per-attribute
auto& positionAttr = createInfo.vertexFormat.attributes[0];
positionAttr.initialData = ...;       // bytes for this attribute only
positionAttr.bufferHandle = ...;

已移除 MeshVertexAttribute::stride。请从格式推导步长：

// Before
auto stride = attr.stride;
// After
auto stride = gfx::getPixelStride(attr.format);

MeshVertexAttribute::dataType 和 MeshVertexAttribute::dimension 已替换为单个 gfx::Format 字段。要一次性转换旧的 (dataType, dimension) 对，请使用辅助函数 toKzGfx(dataType, dimension)。
```
// Before
attr.dataType = GraphicsDataTypeF32;
attr.dimension = 3;
// After
attr.format = gfx::Format::RGB32_Float;
```

已移除无参数的 Mesh::getVertexData()。要获取保留的顶点数据，请使用按特性 (Attribute) 区分的重载：

// Before
const auto& data = mesh.getVertexData();
// After
const auto& data = mesh.getVertexData(VertexAttribute::SemanticPosition);

Mesh::VertexBufferContainer 的值类型已从 Mesh::VertexData { GPUBufferSharedPtr buffer; uint32_t stride; } 更改为 GPUBufferSharedPtr。步长由特性 (Attribute) 格式推导而来；请直接访问缓冲区：
```
// Before
for (const auto& [key, vd] : mesh.getVertexBuffers()) { use(vd.buffer); }
// After
for (const auto& [key, buffer] : mesh.getVertexBuffers()) { use(buffer); }
```
adjustForDeviceCapabilities 现在返回描述所做调整的 vector<Mesh::CreateInfo::Adjustment> （原为 void）。忽略返回值的现有调用无需更改即可编译。
管线验证现在将 UNorm/SNorm/UFloat 通道类型视为与着色器 (Shader) float 输入、ColorRGBA 清除值以及 ColorRGBA 采样器边框颜色兼容。这是一项放宽：以前为通过验证而不得不错误归类清除值或边框颜色的代码不再需要这种变通方法。

gfx::reflection::ReflectionInfo::inputAttributes 和 outputAttributes 现在将特性 (Attribute) 名称映射到 gfx::reflection::Attribute （{ location, component, typeInfo }），而不是直接映射到 gfx::reflection::TypeInfo。读取反射 (Reflection) 类型的代码现在必须通过 .typeInfo 访问：

Kanzi 4.0	Kanzi 4.1
`attribute.second.type`	`attribute.second.typeInfo.type`
`attribute.second.rows`	`attribute.second.typeInfo.rows`
`attribute.second.columns`	`attribute.second.typeInfo.columns`
`attribute.second.arraysize`	`attribute.second.typeInfo.arraysize`

渲染现在会在处理 BeginRenderPipelineCommand 时，根据反射的片段输出和所绑定附件的通道集，验证每个已绑定颜色附件的混合状态写入遮罩 (Mask)。如果混合状态启用了对片段着色器 (Fragment Shader) 不输出的通道的写入，并且所绑定的附件具有这些通道，验证器会报告 commands-color-write-mask-mismatch。根据规范，针对所绑定附件不具备的通道的写入遮罩位在硬件上不起作用（Vulkan，着色器接口——片段输出接口；OpenGL 4.6 Core，§17.4.2 缓冲区更新的精细控制），因此不会被报告。对于过度绑定附件的现有管线，仅当着色器不写入的通道存在于所绑定附件中时，才必须为这些通道清除 colorWriteMask。

DrawObjectsRenderPass::ViewportProperty 已移至 RenderPass 基类，并重命名为 RenderPass::OutputViewportProperty。该属性现在可用于每个渲染通道，而不仅限于 Draw Objects 渲染通道。底层属性标识符已从 "DrawObjectsRenderPass.Viewport" 更改为 "DrawObjectsRenderPass.OutputViewport"。由于先前的标识符已注册为新属性的旧名称，现有的序列化资产仍可继续加载。使用 Java 或 Lua API 的工程现在必须通过 RenderPassMetadata 而不是 DrawObjectsRenderPassMetadata 访问该属性。

Kanzi 4.0

Kanzi 4.1

DrawObjectsRenderPass::ViewportProperty

RenderPass::OutputViewportProperty

Kanzi 4.0	Kanzi 4.1
`DrawObjectsRenderPass::ViewportProperty`	`RenderPass::OutputViewportProperty`

以下 Mesh 方法现在接受一个 VertexAttribute::SemanticKey 参数，用于标识要访问的顶点特性 (Attribute)：Mesh::getVertexBufferHandle、Mesh::getVertexBuffer、Mesh::setVertexData 和 Mesh::setVertexSubData。

您也可以使用 VertexAttribute::Semantic 参数调用 Mesh::getVertexBuffer，以获取与指定语义 (Semantic) 匹配的第一个特性 (Attribute) 的顶点缓冲区。

Kanzi 4.0	Kanzi 4.1
`mesh.getVertexBufferHandle()`	`mesh.getVertexBufferHandle({ VertexAttribute::SemanticPosition, 0u })`
`mesh.getVertexBuffer()`	`mesh.getVertexBuffer({ VertexAttribute::SemanticPosition, 0u })`
`mesh.setVertexData(data)`	`mesh.setVertexData(data, { VertexAttribute::SemanticPosition, 0u })`
`mesh.setVertexSubData(data, offset)`	`mesh.setVertexSubData(data, offset, { VertexAttribute::SemanticPosition, 0u })`

已移除 kanzi::Renderer::setLogging。自迁移到 Kanzi graphics 以来，该方法一直不执行任何操作。请从您的应用程序 (Application) 代码中移除所有对 renderer.setLogging() 的调用。图形 API 调用日志将在未来版本中重新实现。
已移除 kanzi::Renderer::getLogging 和 kanzi::Renderer::getDumpStateOnDrawCalls。请从您的应用程序 (Application) 代码中移除所有对 renderer.getLogging() 和 renderer.getDumpStateOnDrawCalls() 的调用。

运行时 (Runtime) API 的更改¶

TaskDispatcherBase 现已合并到 TaskDispatcher 中，后者已从 kanzi/core.ui/platform/task_dispatcher/common/task_dispatcher.hpp 移至 kanzi/core.ui/task_dispatcher/task_dispatcher.hpp。

迁移方法：

将 task_dispatcher.hpp 的所有 include 指令更新为新位置。
如果您的代码引用了 TaskDispatcherBase，请将其替换为 TaskDispatcher。

Platform 类及其派生的平台专用类已重命名为使用 PlatformContext 后缀。

迁移方法：

将 Platform 替换为 platform::PlatformContext，并更新 include 指令：

Kanzi 4.0

Kanzi 4.1

kanzi/platform/kz_platform/kz_platform.hpp

kanzi/platform/platform_context/platform_context.hpp

Kanzi 4.0	Kanzi 4.1
`kanzi/platform/kz_platform/kz_platform.hpp`	`kanzi/platform/platform_context/platform_context.hpp`

替换平台管理函数：

Kanzi 4.0	Kanzi 4.1
`createDefaultPlatform`	`platform::createDefaultPlatformContext`
`destroyDefaultPlatform`	`platform::destroyDefaultPlatformContext`
`getDefaultPlatform`	`platform::getDefaultPlatformContext`

如果您实现了自定义平台，请重命名您的子类。头文件遵循相同的模式：将 kz_platform/<custom_name>/<custom_name>_platform.hpp 替换为 platform_context/<custom_name>/<custom_name>_platform_context.hpp。

Kanzi 4.0	Kanzi 4.1
`AndroidPlatform`	`platform::AndroidPlatformContext`
`EmscriptenPlatform`	`platform::EmscriptenPlatformContext`
`MacosPlatform`	`platform::MacosPlatformContext`
`QnxPlatform`	`platform::QnxPlatformContext`
`StubPlatform`	`platform::StubPlatformContext`
`WaylandPlatform`	`platform::WaylandPlatformContext`
`Win32Platform`	`platform::Win32PlatformContext`
`X11Platform`	`platform::X11PlatformContext`

GlContextApi 类及其派生的特定平台类已重命名为使用 GlGraphicsContext 后缀。createDefaultGlContextApi 工厂函数已重命名为 platform::makeDefaultGlGraphicsContext。

迁移方法：

将 GlContextApi 替换为 platform::GlGraphicsContext，并将 include 指令从 kanzi/platform/context/gl_context_api.hpp 更新为 kanzi/platform/platform/gl/common/gl_graphics_context.hpp。
将工厂函数调用 createDefaultGlContextApi 替换为 platform::makeDefaultGlGraphicsContext。
在 platform::PlatformContext 实例上，将 getGlContextApi() 替换为 getGlGraphicsContext()。

如果您通过子类化 GlContextApi 实现了自定义 OpenGL 上下文，请重命名您的类。头文件遵循相同的模式：将 context/<name>/<name>_context_api.hpp 替换为 platform/gl/graphics_context/<name>/<name>_graphics_context.hpp。

Kanzi 4.0	Kanzi 4.1
`EglContextApi`	`platform::EglGraphicsContext`
`EglEmscriptenContextApi`	`platform::EglEmscriptenGraphicsContext`
`EglOhosContextApi`	`platform::EglOhosGraphicsContext`
`EglQnxStreamsContextApi`	`platform::EglQnxStreamsGraphicsContext`
`GlxContextApi`	`platform::GlxGraphicsContext`
`WglContextApi`	`platform::WglGraphicsContext`

platform::GlGraphicsContext 的成员函数 getOGLProcAddress 已重命名为 getGLProcAddress。

要进行迁移，请重命名相应的调用。如果您实现了自定义 OpenGL 上下文，请相应地重命名覆盖函数：

Kanzi 4.0	Kanzi 4.1
`getOGLProcAddress`	`getGLProcAddress`

您可以使用新的 getGLProcAddressInto 成员函数，而无需自行将 getGLProcAddress 的结果转换为函数指针类型。该函数根据传入的指针推导函数签名，存储加载的入口点，并返回是否找到了该入口点。

为反映 kzplatform library 的重组，多个平台 API 头文件已移动位置。

要进行迁移，请更新所有引用旧路径的 include 指令：

kanzi/platform/kz_platform_api.hpp -> kanzi/platform/platform_api.hpp
kanzi/platform/graphics/platform_types.hpp -> kanzi/platform/graphics/graphics_types.hpp
kanzi/platform/platform_events.hpp -> kanzi/platform/log/platform_events.hpp
kanzi/platform/utilities/utilities.hpp -> kanzi/platform/windowing_ng/native_accessors.hpp
kanzi/platform/context/vulkan_functions.hpp -> kanzi/platform/platform/vulkan/common/vulkan_functions.hpp
kanzi/platform/graphics/ 中的以下头文件已移至 kanzi/platform/graphics_output/：graphics_output.hpp、framebuffer_graphics_output.hpp、windowed_graphics_output.hpp
kanzi/platform/graphics/make_default_graphics_output.hpp -> kanzi/platform/target/graphics_output/make_default_graphics_output.hpp
kanzi/platform/input/ 中的以下头文件已移至 kanzi/platform/input_ng/：event_filter.hpp、event_queue.hpp、event_source.hpp、event_source_properties.hpp、events.hpp、input_types.hpp、wakeup_signal_source.hpp
kanzi/platform/input/make_default_event_source.hpp -> kanzi/platform/target/input_ng/make_default_event_source.hpp
kanzi/platform/context/ 中的以下头文件已移至 kanzi/platform/windowing/：kzs_surface.h、kzs_surface_configuration.h
kanzi/platform/windowing/ 中的以下头文件已移至 kanzi/platform/windowing_ng/：native_handles.hpp、window_geometry.hpp、window_properties.hpp、window_style.hpp
kanzi/platform/gl/ 中的以下头文件已移至 kanzi/platform/platform/gl/common/：opengl.hpp、gl_function_pointers.hpp、gl_loaders.hpp、kzs_opengl_enum.h

应用程序框架的更改¶

kanzi/core.ui/application/application_properties.hpp 不再包含 kanzi/core.ui/graphics/renderer.hpp。

如果您的代码包含 application_properties.hpp （直接包含，或通过 application.hpp 间接包含），并且在未直接包含 renderer.hpp 的情况下使用了 Renderer 或该文件中声明的其他类型，请添加显式的 include：
```
#include <kanzi/core.ui/graphics/renderer.hpp>
```
移除了 GraphicsLoggingEnabled 应用程序配置选项、ApplicationProperties::graphicsLoggingEnabled 字段以及 --log-graphics 命令行参数。自迁移到 Kanzi graphics 以来，这些项已不再起作用。请从 application.cfg 文件中移除 GraphicsLoggingEnabled = 1，并从应用程序代码中移除对 ApplicationProperties::graphicsLoggingEnabled 或 --log-graphics 的所有引用。

列表框的更改¶

为轨迹列表框 (Trajectory List Box) 引入了新的 TrajectoryListBoxConcept 和 TrajectoryListBoxConceptImpl 类，并为网格列表框 (Grid List Box) 引入了新的 GridListBoxConceptImpl 类。

这样可以更轻松地基于现有行为实现自定义列表框。
ListBoxTrajectoryPresenter 和 ListBoxGridPresenter 现在支持在其派生类中使用 CRTP。

这样可以更轻松地基于现有行为实现自定义呈现器。
为保持一致，所有列表框 concept 类和 Impl 类都已移至 list_box 子目录。

对 Android NDK 版本的更改¶

Android NDK 版本已更新为 28.2.13676358，并且 Kanzi 现在默认支持 16 KB 页面大小，以满足 Android 15 及更高版本设备上的 Google Play 兼容性要求。

要进行迁移，请在应用程序的 build.gradle 文件中将 ndkVersion 设置为 28.2.13676358。

材质的更改¶

在 Material 类中，重命名了以下公开成员函数：

Kanzi 4.0

Kanzi 4.1

Material::acquireDebugMaterialSolid

Material::acquireMaterialSolid

Material::acquireDebugMaterialTextured

Material::acquireMaterialTextured

Kanzi 4.0	Kanzi 4.1
`Material::acquireDebugMaterialSolid`	`Material::acquireMaterialSolid`
`Material::acquireDebugMaterialTextured`	`Material::acquireMaterialTextured`

对应用程序输入事件的更改¶

为了与应用程序状态保持一致，应用程序输入事件 sleep 和 wakeup 已重命名为 paused 和 resumed。请更改代码中的事件类型和函数调用以使用新名称：

Kanzi 4.0	Kanzi 4.1
`InputEvent::Type::ApplicationSleep`	`InputEvent::Type::ApplicationPaused`
`InputEvent::Type::ApplicationWakeup`	`InputEvent::Type::ApplicationResumed`
`addApplicationSleepEvent()`	`addApplicationPausedEvent`
`addApplicationWakeupEvent()`	`addApplicationResumedEvent`

之前未使用的 InputEvent::Type::ApplicationPaused 事件现在用于报告应用程序已暂停并已转换到 MainLoopState::Paused。此事件承担之前由 ApplicationSleep 承担的功能。

材质类型命令的更改¶

已删除 SaveMaterialType 命令。要在工程之间共享材质类型，请改用 ExportProjectItems。
LoadMaterialType 命令已弃用。要从 .kzexport 存档导入材质类型，请改用 ImportProjectItems。

TextBoxConcept API 的更改¶

重命名了 TextBoxConcept 中消息参数的元类，使其与所属类的名称一致。

要迁移您的 Kanzi Engine Lua API 和 Kanzi Java API 应用程序，请将 TextBoxMetadata 重命名为 TextBoxConceptMetadata。

TextInputManipulator API 的更改¶

重命名了 TextInputManipulator 中消息参数的元类，使其与所属类的名称一致。

要迁移您的 Kanzi Engine Lua API 和 Kanzi Java API 应用程序，请将 TextInputConceptMetadata 重命名为 TextInputManipulatorMetadata。

Kanzi Engine Lua API 的更改¶

弃用了 PropertyType:new 和 MessageType:new 方法，改为使用 PropertyType:find 和 MessageType:find。

要迁移您的 Kanzi Engine Lua API 脚本，请将 PropertyType:new 重命名为 PropertyType:find，将 MessageType:new 重命名为 MessageType:find。

Lua 中的多个构造函数已从 create 重命名为 create1。

Kanzi 4.0	Kanzi 4.1
`CallbackBindingProcessor:create`	`CallbackBindingProcessor:create1`
`NodeEffectPrefab2D:create`	`NodeEffectPrefab2D:create1`
`RangeBindingProcessor:create`	`RangeBindingProcessor:create1`
`RenderPassPrefab:create`	`RenderPassPrefab:create1`

平台的更改¶

删除了 listEGLAttributes，改为使用更灵活的 formatEGLAttributes，该函数会创建格式化的、便于阅读的字符串。

要进行迁移，请使用 formatEGLAttributes 格式化特性，然后将格式化后的字符串传递给 kzLogInfo。
```
// Before migration.
listEGLAttributes("EGL context attributes", attribs);

// After migration.
kzLogInfo(KZ_LOG_CATEGORY_EGL, ("{}", formatEGLAttributes("EGL context attributes", attribs)));
```
platform::createDefaultPlatformContext、platform::destroyDefaultPlatformContext 和 platform::getDefaultPlatformContext 从 platform_context.hpp 移至一个新的专用头文件。

要进行迁移，请更新 include：
```
// Before migration.
#include <kanzi/platform/platform_context/platform_context.hpp>

// After migration.
#include <kanzi/platform/target/platform_context/default_platform_context.hpp>
```

PropertyFieldAnimationTimelinePlayback 的更改¶

PropertyFieldAnimationTimelinePlayback 的受保护构造函数新增了一个参数：

// Kanzi 4.0
explicit PropertyFieldAnimationTimelinePlayback(
    PropertyFieldAnimationTimelineSharedPtr, ObjectSharedPtr, bool relative);

// Kanzi 4.1
explicit PropertyFieldAnimationTimelinePlayback(
    PropertyFieldAnimationTimelineSharedPtr, ObjectSharedPtr, bool relative,
    const optional<TimelinePlaybackContext::RuntimeEnvironment>& runtimeEnv);

如果您派生 PropertyFieldAnimationTimelinePlayback 的子类并直接调用受保护构造函数，请为 runtimeEnv 传递 nullopt 以保留之前的行为。

此外，该类现在显式删除了复制构造函数、移动构造函数以及复制赋值运算符和移动赋值运算符。

PipelineStateRenderPass 颜色写入模式的更改¶

已删除 GraphicsColorWriteMode 枚举，并替换为 gfx::ColorWriteMask，这是一种位掩码标志类型，可以组合各个通道标志。

PipelineStateRenderPass::ColorWriteModeProperty 的类型从 PropertyType<GraphicsColorWriteMode> 更改为 kanzi::PropertyType<kanzi::gfx::ColorWriteMask>。getColorWriteMode() 和 setColorWriteMode() 访问器现在使用 gfx::ColorWriteMask。

由于 gfx::ColorWriteMask 是位掩码，您可以使用按位或运算符组合通道标志：

// Kanzi 4.0
renderPass->setColorWriteMode(GraphicsColorWriteModeRGBA);

// Kanzi 4.1
renderPass->setColorWriteMode(gfx::ColorWriteMask::RGBA);
renderPass->setColorWriteMode(gfx::ColorWriteMask::R | gfx::ColorWriteMask::G);

下表列出了旧枚举值与对应新标志之间的映射：

Kanzi 4.0 (`GraphicsColorWriteMode`)	Kanzi 4.1 (`gfx::ColorWriteMask`)
`GraphicsColorWriteModeNone`	`gfx::ColorWriteMask::None`
`GraphicsColorWriteModeRGB`	`gfx::ColorWriteMask::RGB`
`GraphicsColorWriteModeRGBA`	`gfx::ColorWriteMask::RGBA`
`GraphicsColorWriteModeR`	`gfx::ColorWriteMask::R` \| `gfx::ColorWriteMask::A`
`GraphicsColorWriteModeG`	`gfx::ColorWriteMask::G` \| `gfx::ColorWriteMask::A`
`GraphicsColorWriteModeB`	`gfx::ColorWriteMask::B` \| `gfx::ColorWriteMask::A`
`GraphicsColorWriteModeGB`	`gfx::ColorWriteMask::G` \| `gfx::ColorWriteMask::B` \| `gfx::ColorWriteMask::A`
`GraphicsColorWriteModeA`	`gfx::ColorWriteMask::A`

备注

该枚举的整数值已更改。新类型使用 2 的幂位掩码值（R=1、G=2、B=4、A=8），而不再使用之前的连续索引。请更新存储或比较 GraphicsColorWriteMode 原始整数值的所有应用程序代码。在 Kanzi Studio 4.1 中打开 .kzm 工程文件时，这些文件会自动迁移。

在 Kanzi Studio 插件接口中，PipelineStateRenderPassColorWriteMode 从 TypedProperty<ColorWriteModeEnum> 更改为 TypedProperty<int>，并且移除了 ColorWriteModeEnum 类型。请更新读取或写入该属性的插件代码，改为使用原始整数标志值（Red=1、Green=2、Blue=4、Alpha=8）。

在 Kanzi Engine Lua API 中，将已移除的 GraphicsColorWriteMode 表替换为 gfx.ColorWriteMask：

Kanzi 4.0 (`GraphicsColorWriteMode`)	Kanzi 4.1（`gfx.ColorWriteMask`）
`GraphicsColorWriteMode.GraphicsColorWriteModeNone`	`gfx.ColorWriteMask.None`
`GraphicsColorWriteMode.GraphicsColorWriteModeRGBA`	`gfx.ColorWriteMask.RGBA`
`GraphicsColorWriteMode.GraphicsColorWriteModeRGB`	`gfx.ColorWriteMask.RGB`
`GraphicsColorWriteMode.GraphicsColorWriteModeR`	`gfx.ColorWriteMask.R \| gfx.ColorWriteMask.A`
`GraphicsColorWriteMode.GraphicsColorWriteModeG`	`gfx.ColorWriteMask.G \| gfx.ColorWriteMask.A`
`GraphicsColorWriteMode.GraphicsColorWriteModeB`	`gfx.ColorWriteMask.B \| gfx.ColorWriteMask.A`
`GraphicsColorWriteMode.GraphicsColorWriteModeGB`	`gfx.ColorWriteMask.G \| gfx.ColorWriteMask.B \| gfx.ColorWriteMask.A`
`GraphicsColorWriteMode.GraphicsColorWriteModeA`	`gfx.ColorWriteMask.A`

在 Kanzi Java API 中，将 GraphicsColorWriteMode 替换为 ColorWriteMask，并相应地更新对 PipelineStateRenderPassMetadata.ColorWriteModeProperty 的引用。
在 Kanzi Studio 4.1 中打开包含 PipelineStateRenderPass.ColorWriteMode 值的 .kzm 工程文件时，这些值会自动迁移为新的标志表示形式。

对 Kanzi 文档 MCP 服务器的更改¶

新的统一 Kanzi 文档 MCP 服务器已在 https://docs.mcp.kanzi.com/mcp 提供，并在 https://docs.kanzi.com/mcp/kanzi-docs-mcp.zip 提供适用于 Claude Desktop 的新 mcpb 包。新端点支持所有已加载的 Kanzi 版本。

现有的特定版本 URL（kanzi-docs-mcp-v3-9.* 和 kanzi-docs-mcp-v4-0.*）仍受支持。要使用新的集成，请迁移到统一 URL。请参阅 Kanzi 文档 MCP 服务器。

如果您之前在 MCP 客户端配置中添加了特定版本的条目（例如 kanzi-docs-v3-9 或 kanzi-docs-v4-0），请在添加统一的 kanzi-docs 条目后移除这些条目。保留重复的条目可能导致客户端启动时挂起。

对着色器编译的更改¶

从 Kanzi 4.1.0 开始，材质中的着色器 源代码 必须使用 GLSL ES 310+ 或桌面 GLSL 140+ 语法。旧版 GLSL 结构（attribute、varying、gl_FragColor、gl_FragData[N]）不再受支持。您必须更新 Kanzi Studio 工程中仍使用旧版语法的着色器。

这是对着色器编写要求的更改，而不是对部署要求的更改。Kanzi 会将您的着色器源代码交叉编译为工程的 Target Graphics API 设置所要求的 GLSL 方言，因此您仍然可以部署到 OpenGL ES 3.0。例外情况是您的着色器使用了 GLSL ES 3.1 或更高版本中引入的功能，例如计算着色器、图像加载/存储、着色器存储缓冲区对象等。源代码中使用的功能必须在所选的 Target Graphics API 上可用。

要迁移着色器，请应用以下变换：

旧版语法	替换内容
`attribute`	`in` （顶点着色器输入）
`varying` （顶点着色器）	`out` （顶点着色器输出）
`varying` （片段着色器）	`in` （片段着色器输入）
`gl_FragColor`	使用 `layout(location = 0) out vec4 fragColor;` 声明的用户定义输出变量
`gl_FragData[N]`	使用 `layout(location = N) out vec4 fragDataN;` 声明的用户定义输出变量
缺少 `#version`	添加 `#version 310 es` （嵌入式系统）或 `#version 460` （桌面）
`#version 100` 或 `#version 300 es`	`#version 310 es`
`main()` 内部的 `precision`	将 `precision` 移至 `main()` 之前的全局作用域。ES 310 要求在片段着色器中为浮点数设置全局精度。
`texture2D(sampler, uv)`	`texture(sampler, uv)`
`textureCube(sampler, uv)`	`texture(sampler, uv)`

其他注意事项：

命名 Uniform 块必须使用显式 layout 限定符。将 uniform BlockName { ... }; 替换为 layout(std140, binding = N, set = M) uniform BlockName { ... };。
Kanzi 将描述符集 0、绑定 0 保留给自动生成的 Uniform 块，该块存放松散的 Uniform（例如 uniform float Opacity;）。如果您的材质类型在集 0、绑定 0 处使用自定义 Uniform 块，请将其移至其他绑定。
您在 Project Properties 中选择的 Target Graphics API 决定了您可以使用哪些 ES 310 / GL 140 功能。计算着色器、图像加载/存储以及着色器存储缓冲区对象要求 Target Graphics API 为 OpenGL ES 3.1 或更高版本（或对应的桌面版本）。仅使用 ES 310 语法（in / out、texture()、命名输出变量）的着色器仍可顺利交叉编译到 OpenGL ES 3.0 目标。

有关更新后的着色器编写参考，请参阅设置 OpenGL ES 版本。

另请参阅¶

Kanzi 4.1.0 版本说明

已知问题