Kanzi 3.4 migration guide¶

Use this migration guide to update Kanzi applications from Kanzi 3.3 to Kanzi 3.4.

Kanzi libraries¶

Kanzi libraries are now available only for Visual Studio 2013 and 2015. To replace the Visual Studio 2010 configurations in your old projects with Visual Studio 2015 configurations:

Open the Visual Studio solution of the project in Visual Studio:
1. In the Solution Explorer right-click the project, select Properties > General > Platform Toolset, and make sure that the Visual Studio 2015 v140 compiler is selected. If your project includes a Kanzi Engine plugin, do this for the plugin and executable projects.
2. In the Property Manager rename the 2010 configurations to 2015. In Visual Studio you can find the Property Manager in View > Property Manager or in View > Other Windows > Property Manager. For example, rename the “GL_vs2010_Release” configuration to “GL_vs2015_Release”.
3. In the Property Manager select all ES_IMG configurations, right-click and select Remove.
4. In the Configuration Manager rename the 2010 configurations to 2015 and set each configurations to use the correct configuration for Visual Studio 2015, which you renamed in the Properties Manager.
  
  For example, open the Configuration Manager, in the Active solution configuration dropdown menu select <Edit…>, rename “GL_vs2010_Release” to “GL_vs2015_Release”, and in the Configuration Manager set all projects to use the “GL_vs2015_Release” configuration.
5. In Visual Studio build all configurations of the plugins you want to use.
Open the Kanzi Studio project in Kanzi Studio and let Kanzi Studio convert the project to the current version.
In Kanzi Studio in the Library > Kanzi Engine Plugins select the GL VS2010 Debug and Release versions of the plugin and in the Properties set the plugin.

For example, for GL VS2015 Release plugin in the Library > Kanzi Engine Plugins select the GL VS2010 Release plugin and in the Properties set:
- Name to GL VS2015 Release
- Windows DLL Path to ..ApplicationlibWin32GL_vs2015_Release_DLL<ProjectName>.dll
- Visual Studio Version to 2015

Change in the `MOD()` binding function¶

When Kanzi Studio converts projects created in the previous version of Kanzi, it changes the MOD() functions in the bindings to the newly introduced REM() functions. This conversion preserves the calculation result.

In Kanzi 3.4 the REM() function returns the same value as the MOD() function returned in the earlier Kanzi versions, while the modified MOD() function introduced in Kanzi 3.4 now returns a different result. See mod (modulo) and rem (remainder).

Runtime switching between OpenGL and OpenGLES¶

On the Windows operating system you can select whether you want to use OpenGL ES or OpenGL in the Application::onConfigure function, in the application.cfg, or using the command line arguments, if your target supports command line arguments.

Separate ES2_IMG configurations no longer exist.

In the application.cfg use:

GraphicsBackend to either of these values:
- GLES
- OpenGL
GraphicsContextAPI to either of these values:
- EGL
- WGL

In the Application::onConfigure() use:

configuration.defaultSurfaceProperties.type to either of these values:
- KZS_SURFACE_TYPE_ES2_ONLY (surface is target for OpenGLES 2.0 rendering)
- KZS_SURFACE_TYPE_GL_ONLY (surface is target for OpenGL rendering)
configuration.defaultSurfaceProperties.contextApi to either of these values:
- KZS_GRAPHICS_CONTEXT_API_WGL (use WGL for graphics context)
- KZS_GRAPHICS_CONTEXT_API_EGL (use EGL for graphics context)

On the command line use:

-gles to use OpenGL ES
-gl to use OpenGL
-egl to use EGL
-wgl to use WGL
-glx to use GLX

See Graphics library.

Changed include paths¶

The include path for these Kanzi Engine includes related to graphics is now kanzi/graphics_backend:

graphics
- 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

For example, update the old path

#include <kanzi/graphics3d/texture.hpp>

to the new path

#include <kanzi/graphics_backend/texture.hpp>

Graphics changes¶

New graphics creation pattern¶

Kanzi 3.4 streamlines the API for managing textures and render targets. The new API provides means to validate support for particular graphics hardware features and ensures that texture objects are fully constructed and always usable.

Texture changes¶

Texture class supports textures with image data and render target textures.

There are different specialized subclasses of the CreateInfo class which are included for your convenience:

CreateInfo2D
CreateInfoHostCopy2D
CreateInfoRenderTarget2D
CreateInfoCubemap

You can still modify the parameters of CreateInfo before passing them to the Texture::create() function.

To create a texture first use Texture::CreateInfo to prepare the structure and then pass it to the Texture constructor, or TextureSharedPtr Texture::create() function.

After you create a texture you cannot modify the texture parameters which you passed in the Texture::CreateInfo.

Texture creation now throws an exception if you pass wrong parameters or parameters not supported by the graphics device to the Texture::CreateInfo.

If you load a texture from a kzb file and the texture validation fails, Kanzi uses a default texture and writes a warning message to the log.

Framebuffer changes¶

Framebuffer is a Kanzi Engine feature that supports complex configuration of OpenGL pipeline. It is used internally in RenderPass class to implement features like multiple render targets or rendering to a particular mipmap level. Use render passes in Kanzi Studio to configure complex OpenGL pipeline.

Shader changes¶

Blend Mode (StandardMaterial::BlendModeProperty) is no longer a property that you can add or remove in a shader.

Renderer changes¶

Replaced setActiveSurface() with setActiveGraphicsOutput().

Material type changes¶

If you load a Kanzi 3.2 project, it may contain nodes (for example Image 2D) using materials with material types which do not use the Blend Mode property. To maintain the desired effect in materials, before loading the project in Kanzi 3.4 make the following changes in Kanzi 3.2:

Add the Blend Mode property to those material types which do not use it.
Set the Blend Mode property for the materials which use those material types, and optionally for individual nodes.

Scale, rotation, transformation changes¶

2D and 3D nodes transformation properties are described by SRTValue2D and SRTValue3D structures. Matrix3x3 and Matrix4x4 structures are no longer used for this purpose. See SRTValue2D and SRTValue3D.

SRTValue3D stores rotation as a quaternion which allows creating of smoother rotations in animations, but can produce different results than when you use Euler angles.

Page class split into Page and PageHost classes¶

If you created Page nodes in code, the Page node is split into classes Page and PageHost. You must create a Page Host node as the root node in any Page or Page Host hierarchy.

These properties are no longer in the Page class, but in the PageHost class:

DefaultSubPageProperty
LoopSubPagesProperty

These message types are no longer in the Page class, but in the PageHost class:

NavigationStartedMessage
NavigationFinishedMessage
NavigateNextMessage
NavigatePreviousMessage

Replaced message argument C API with C++ API¶

See the MessageArguments class.

Input manipulators converted to C++¶

If you use input manipulators in code, see the API documentation of the related input manipulator class.

Box, sphere, and plane changes¶

Mesh::generateBox is now Mesh::createBox.

Mesh::generateSphere is now Mesh::createSphere.

Mesh::generatePlane is now Mesh::createPlane.

Metadata changes¶

Declaring metadata for message types and property types has changed. You are required to use kzMakeFixedString macro to provide the name of the property or message type. See <KanziWorkspace>/Examples/Node2D_plugin and <KanziWorkspace>/Examples/Node3D_plugin examples.

Animation system¶

This is the last version of Kanzi which contains the old C animation API. This means that some of the features of the old animation system are going to be removed in the next version of Kanzi. See Known issues.

Please provide feedback whether you want to continue using the features which were included in the old C API animation system, but are not included in the new C++ API animation system.