Kanzi 3.9.6 migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.9.5 to Kanzi 3.9.6.

Changes to kanzi::variant

Changed the C++ typedef for kanzi::variant from boost::variant to boost::variant2.

The boost::variant2 uses the same API as C++17 std::variant, but that is different from the previously used API of boost::variant.

For example, to migrate your Kanzi application:

  • Replace v.which() with v.index().

  • Replace v.type() == typeid(T) with holds_alternative<T>(v).

  • Remove derivation from boost::static_visitor for all visitor classes.

  • Replace v.apply_visitor(visitor) and apply_visitor(visitor, v) with visit(visitor, v).

Changes to header files

Kanzi Engine now uses more forward declarations and no longer contains unnecessary includes in header files domain.hpp and metaclass.hpp. To migrate your Kanzi application, include the missing headers.

For example, previously it was possible to use kanzi::TaskDispatcher and kanzi::ResourceDictionary with

#include <kanzi/core.ui/domain/domain.hpp>

but now you need to use

#include <kanzi/core.ui/domain/domain.hpp>
#include <kanzi/core.ui/task_dispatcher/task_dispatcher.hpp>
#include <kanzi/core.ui/resource/resource_dictionary.hpp>

Changes to CMake configuration files

Cotire CMake module is not longer available in the Kanzi workspace. If you want to continue using the module, you can get it from https://github.com/sakra/cotire or from a previous Kanzi release. However, we recommend that you migrate your CMake configuration files to use the CMake built-in feature target_precompile_headers that is available starting with the CMake version 3.16.

Changes to Kanzi Java API Custom Resource Manager Protocol

When using a Kanzi Java API Custom Resource Manager Protocol, the resource is now behind an ObjectRef instance, instead of using a non-owning Resource reference. This ensures that the lifetime of the created object does not get reclaimed by the JVM garbage collector while the resource is still being loaded.

When implementing synchronous loading, the ResourceManager.ProtocolHandler.Result constructor has changed to accept an ObjectRef<? extends Resource> instead of a simple Resource. Change the code that uses this constructor to provide an owning ObjectRef instance.

Kanzi 3.9.5

Kanzi 3.9.6

public Result(Resource resource)

public <TResultType extends Resource> Result(ObjectRef<TResultType>

When implementing asynchronous loading, the ResourceManager.LoadTask.getResult() method now returns an ObjectRef<? extendes Resource> instead of a simple Resource. Typically the LoadTask instance already has access to the ObjectRef from creating the resource. The recommendation is to return a clone of that internal ObjectRef instance using the clone() method.

Kanzi 3.9.5

Kanzi 3.9.6

abstract public Resource getResult();

abstract public ObjectRef<? extends Resource> getResult();

Added the ResourceManager.LoadTask.close() method that you can override in extended classes. If needed, this allows explicit memory cleanup of internal LoadTask resources.

Changes to brush rendering

To improve performance on GPUs that use tile-based rendering, Kanzi no longer tries to avoid clearing framebuffers during 2D rendering.

The improvement introduces these changes in the BrushRenderer interface:

Kanzi 3.9.5

Kanzi 3.9.6

void updateRender(optional<int> blendMode, bool forceOpaque, bool translucencyHint)

void updateRender(optional<int> blendMode, bool translucencyHint)

virtual void updateRenderOverride(optional<int> blendMode, bool forceOpaque, bool translucencyHint) = 0;

virtual void updateRenderOverride(optional<int> blendMode, bool translucencyHint) = 0;

The changes affect:

  • Custom classes derived from BrushRenderer

  • Application code that renders content using brushes manually

Changes to shader creation

Kanzi 3.9.6. adds support for geometry and tessellation shaders. The improvement introduced these changes in ShaderProgram::CreateInfo:

  • Replaced the vertex and fragment shader-specific fields with more generic variants.

  • Changed binary data types from string to byte vectors.

The convenience classes ShaderProgram::CreateInfoShaderSource and ShaderProgram::CreateInfoShaderBinary remain the same.

Kanzi 3.9.5

Kanzi 3.9.6

string vertexShaderSource and string fragmentShaderSource

void addSourceShader(ShaderType type, string_view source) or void addSourceShader(ShaderType type, const char* source)

string separateShaderBinaryVertexData and string separateShaderBinaryFragmentData

void addBinaryShader(ShaderType type, ConstByteSpan binary)

string programBinaryData

vector<byte> programBinaryData

string combinedShaderBinaryData

vector<byte> combinedShaderBinaryData

Changes to focus and input management

In Kanzi 3.9.6, a Node knows the Screen node to which it is attached and can get the FocusManager and InputManager instances from that Screen.

Introduced these functions:

  • Node::getFocusManager() and Node::getInputManager() get the FocusManager and InputManager instances associated to the Screen node to which a node belongs.

  • Node::getScreen() and Node::setScreen() get and set the Screen node to which a node belongs.

  • Screen::setFocusManager() and Screen::setInputManager() associate a FocusManager and an InputManager to a Screen node.

Removed these functions:

  • Domain::getFocusManager(). Use Node::getFocusManager() instead.

  • Domain::getInputManager(). Use Node::getInputManager() instead.

Changes to accessing Kanzi Java API from Kanzi Android framework (droidfw)

If the root node of the prefab displayed in a Kanzi view is a Screen node, the getRoot() method now returns the child of that Screen node. In previous versions of Kanzi, the method returned the Screen node. See Accessing the Kanzi Java API.

Changes to KzuEngine

Deprecated the kzuEngine structure and moved its functionality to the Application, Node, ResourceManager, and Screen classes:

Kanzi 3.9.5

Kanzi 3.9.6

kzuEngineLoadBinary()

Application::loadKzbFile()

kzuEngineGetScreen()

Application::getScreen()

kzuEngineSetScreen()

Application::setScreen()

kzuEngineGetRootCompositionTarget()

Application::getRootCompositionTarget()

kzuEngineSetRootCompositionTarget()

Application::setRootCompositionTarget()

kzuEngineGetRenderingAreaOffset()

Application::getRenderingAreaOffset()

kzuEngineSetRenderingAreaOffset()

Application::setRenderingAreaOffset()

kzuEngineMeasurePerformance()

Application::measurePerformance()

kzuEngineGetFramesPerSecond()

Application::getFramesPerSecond()

kzuEngineRestoreNodeResources()

Application::restoreNodeResources()

kzuEngineInvalidateScreenLayout()

Node::invalidateMeasure()

kzuEngineInvalidateGPUResources()

ResourceManager::invalidateAllGPUResources()

kzuEngineSetScreenOrientation()

Screen::setWindowOrientation()

This change makes the kzuEngineCreate(), kzuEngineDelete(), and Application::getEngine() functions obsolete.

Other changes

  • In the GatherLightsRenderPass::checkLightsModified() function, introduced the lightRange parameter that specifies the light range to check. You can use this function in a custom render pass that inherits the GatherLightsRenderPass.

  • In PropertyAccessRange, the adapt() functions now take as input a range reference instead of a shared_ptr.