Kanzi 3.4 迁移指南

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

Kanzi 库

Kanzi 库现在仅适用于 Visual Studio 2013 和 2015。要将旧项目中的 Visual Studio 2010 配置替换为 Visual Studio 2015 配置：

  1. 在 Visual Studio 中打开工程的 Visual Studio 解决方案：

    1. 在 Solution Explorer 中右键点击工程，选择属性> 通用> 平台工具集 (Properties > General > Platform Toolset)，并确保选中了 Visual Studio 2015 v140 编译器。如果您的项目包含 Kanzi Engine 插件，请对插件和可执行项目执行此操作。

      ../../_images/set-platform-toolset-compiler.png

    2. 在 Property Manager 中将 2010 配置重命名为 2015。在 Visual Studio 中，您可以在 View > Property Manager 或在 View > Other Windows > Property Manager 中找到 Property Manager。例如，将 “GL_vs2010_Release” 配置重命名为 “GL_vs2015_Release”。

      ../../_images/rename-configurations.png

    3. 在属性管理器中，选择所有 ES_IMG 配置，右键点击并选择移除 (Remove)。

    4. 在配置管理器中，将 2010 配置重命名为 2015，并将每个配置设置为使用在属性管理器中重命名的 Visual Studio 2015 的正确配置。

      例如，打开配置管理器，在活动解决方案配置下拉菜单中选择 <Edit …>，将 “GL_vs2010_Release” 重命名为 “GL_vs2015_Release”，并在配置管理器中将所有工程设置为使用 “GL_vs2015_Release” 配置。

      ../../_images/open-configuration-manager.png ../../_images/rename-configurations-in-configuration-manager.png

    5. 在 Visual Studio 中，构建要使用的插件的所有配置。

  2. 在 Kanzi Studio 中打开 Kanzi Studio 项目，并让 Kanzi Studio 将项目转换为当前版本。

  3. 在 Kanzi Studio 中，在 Library > Kanzi Engine Plugins 中选择插件的 GL VS2010 Debug 和 Release 版本，并在 Properties 中设置插件。

    例如：对于 Library > Kanzi Engine Plugins 中的 GL VS2015 Release 插件，选择 GL VS2010 Release 插件，并在 Properties 中设置：

    • Name 到 GL VS2015 Release

    • Windows DLL Path 到 ..ApplicationlibWin32GL_vs2015_Release_DLL<ProjectName>.dll

    • Visual Studio 版本为 2015

      ../../_images/engine-plugin-properties.png

在 MOD() 绑定函数中进行更改。

当 Kanzi Studio 转换在先前版本的 Kanzi 中创建的项目时，它将绑定中的 MOD() 函数更改为新引入的 REM() 函数。此转换保留了计算结果。

在 Kanzi 3.4 中，REM() 函数返回的值与早期 Kanzi 版本中的 MOD() 函数返回的值相同，而在 Kanzi 3.4 中引入的修改后的 MOD() 函数现在返回不同的结果。请参阅 mod（模数） 和 rem（余数）。

在 OpenGL 与 OpenGLES 之间进行运行时切换

在 Windows 操作系统上，您可以在 Application::onConfigure 函数中、application.cfg 中或使用命令行参数（如果您的目标支持命令行参数）选择要使用 OpenGL ES、OpenGL 还是 Vulkan。

单独的 ES2_IMG 配置不再存在。

在 application.cfg 中使用：

  • GraphicsBackend 为以下任一值：

    • GLES

    • OpenGL

  • GraphicsContextAPI 为以下任一值：

    • EGL

    • WGL

在 Application::onConfigure() 中使用：

  • 将 configuration.defaultSurfaceProperties.type 设置为以下任一值：

    • KZS_SURFACE_TYPE_ES2_ONLY （surface 是 OpenGLES 2.0 渲染的目标）

    • KZS_SURFACE_TYPE_GL_ONLY （surface 是 OpenGL 渲染的目标）

  • configuration.defaultSurfaceProperties.contextApi 为以下任一值：

    • KZS_GRAPHICS_CONTEXT_API_WGL （使用 WGL 作为图形上下文）

    • KZS_GRAPHICS_CONTEXT_API_EGL （使用 EGL 作为图形上下文）

在命令行使用：

  • --gles 或 --opengles 以使用 OpenGL ES

  • --gl 或 --opengl 以使用 OpenGL

  • --vk 或 --vulkan 以使用 Vulkan

  • --egl 以使用 EGL

  • --wgl 以使用 WGL

  • --glx 以使用 GLX

请参阅 图形库。

include 路径中的更改

这些与图形相关的 Kanzi Engine 的包含路径现在是 kanzi/graphics_backend：

  • 图形

    • gl_graphics_output.hpp

  • graphics2d

    • brush_renderer.hpp

    • color_brush_renderer.hpp

    • composition_brush_renderer.hpp

    • content_brush_renderer.hpp

    • gl_brush_renderer.hpp

    • material_brush_renderer.hpp

    • texture_brush_renderer.hpp

  • graphics3d

    • framebuffer.hpp

    • renderbuffer.hpp

    • sampler.hpp

    • shader.hpp

    • texture.hpp

    • renderer3d.hpp

    • gpu_resource

  • 渲染 (Rendering)

    • gl_program_handle.hpp

    • gl_render_state*

    • gl_shader_handle.hpp

    • renderer.hpp

例如，更新旧路径

#include <kanzi/graphics3d/texture.hpp>

为新路径

#include <kanzi/graphics_backend/texture.hpp>

图形更改

新图形创建模式

Kanzi 3.4 简化了管理纹理和渲染目标的 API。新的 API 提供了验证特定图形硬件功能支持的方法，并确保纹理对象完全构建且始终可用。

纹理更改

Texture 类支持有图像数据的纹理和渲染目标纹理。

为方便起见，CreateInfo 类有不同的专用子类：

  • CreateInfo2D

  • CreateInfoHostCopy2D

  • CreateInfoRenderTarget2D

  • CreateInfoCubemap

在将 CreateInfo 传递给 Texture::create() 函数之前，您仍然可以修改其参数。

要创建纹理，首先使用 Texture::CreateInfo 准备结构，然后将其传递给 Texture 构造函数，或 TextureSharedPtr Texture::create() 函数。

您创建纹理后，无法修改在 Texture::CreateInfo 中传递的纹理参数。

现在，如果将错误的参数或图形设备不支持的参数传递给 Texture::CreateInfo，纹理创建将抛出异常。

如果从 kzb 文件加载纹理且纹理验证失败，Kanzi 使用默认纹理并将警告消息写入日志。

帧缓冲区更改

Framebuffer 是一个 Kanzi Engine 功能，支持 OpenGL 管道的复杂配置。它在 RenderPass 类中被内部使用，以实现诸如多重渲染目标或渲染到特定 mipmap 级别的功能。在 Kanzi Studio 中使用渲染通道来配置复杂的 OpenGL 管道。

着色器更改

Blend Mode (StandardMaterial::BlendModeProperty) 不再是可以在着色器中添加或删除的属性。

Renderer 更改

将 setActiveSurface() 替换为 setActiveGraphicsOutput()。

材质类型更改

如果您加载一个 Kanzi 3.2 项目，它可能包含使用不使用 Blend Mode 属性的材质类型的节点（例如 Image 2D）。为了在材质中保持所需效果，在 Kanzi 3.4 中加载项目之前，请在 Kanzi 3.2 中进行以下更改：

  • 将 Blend Mode 属性添加到不使用它的那些材质类型中。

  • 为使用这些材质类型的材质设置 Blend Mode 属性，并可选择为单个节点设置。

缩放、旋转、变换更改

2D 和 3D 节点的变换属性由 SRTValue2D 和 SRTValue3D 结构描述。Matrix3x3 和 Matrix4x4 结构不再用于此目的。请参阅 SRTValue2D 和 SRTValue3D。

SRTValue3D 将旋转存储为四元数，这允许在动画中创建更平滑的旋转，但可能会产生与使用欧拉角时不同的结果。

页面类分为 Page 和 PageHost 类

如果您在代码中创建了 Page 节点，Page 节点将被拆分为 Page 和 PageHost 类。您必须创建一个 Page Host 节点作为任何 Page 或 Page Host 层次结构中的根节点。

这些属性不再在 Page 类中，而是在 PageHost 类中：

  • DefaultSubPageProperty

  • LoopSubPagesProperty

这些消息类型不再位于 Page 类中，而是在 PageHost 类中：

  • NavigationStartedMessage

  • NavigationFinishedMessage

  • NavigateNextMessage

  • NavigatePreviousMessage

将消息参数 C API 替换为 C++ API

请参阅 MessageArguments 类。

输入操纵器转换为 C++

如要在代码中使用输入操纵器，请参阅相关输入操纵器类的 API 文档。

框、球体和平面更改

Mesh::generateBox 现在是 Mesh::createBox。

Mesh::generateSphere 现在是 Mesh::createSphere。

Mesh::generatePlane 现在是 Mesh::createPlane。

元数据更改

声明消息类型和属性类型的元数据已更改。您需要使用 kzMakeFixedString 宏来提供属性或消息类型的名称。请参阅 <KanziWorkspace>/Examples/Node2D_plugin 和 <KanziWorkspace>/Examples/Node3D_plugin 示例。

动画系统 (Animation System)

这是包含旧 C 动画 API 的最后一个 Kanzi 版本。这意味着旧动画系统的一些功能将在下一个 Kanzi 版本中被移除。请参阅 已知问题。

请反馈您是否要继续使用旧 C API 动画系统中包含、而新的 C++ API 动画系统中没有的功能。

另请参阅

Kanzi 3.4 发行说明

已知问题