Kanzi 3.9.4 migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.9.3 to Kanzi 3.9.4.

Changes to the Face to Camera properties of 3D nodes

Replaced the Face to Camera, Face to Camera is Billboarding, and Face to Camera Cylindrical boolean properties with the Face to Camera Mode enumeration property.

This table lists the changes to the properties and methods in the Constraints class:

Kanzi 3.9.3

Kanzi 3.9.4

FaceToCameraProperty

FaceToCameraIsBillboardingProperty

FaceToCameraCylindralProperty

FaceToCameraModeProperty

bool isFaceToCamera(const Object& object)

FaceToCameraMode getFaceToCameraMode(const Object& object)

void setFaceToCamera(Object& object, bool value)

void setFaceToCameraMode(Object& object, FaceToCameraMode value)

bool isFaceToCameraBillboarding(const Object& object)

void setFaceToCameraIsBillboarding(Object& object, bool value)

bool isFaceToCameraCylindral(const Object& object)

void setFaceToCameraIsCylindral(Object& object, bool value)

Changes in Java API

In these Assert functions, changed the type of the error message argument to a callback that returns a string. This prevents redundant string allocation for passing assertions:

  • True

  • NotNull

  • Null

For example, Assert.True call changes from

Assert.True(isValid(), "Error message");

to

Assert.True(isValid(), () -> "Error message");

Changes to text and 2D geometry rendering

Kanzi now renders text and all 2D geometry using virtual buffer objects and interleaved vertex buffers instead of rendering from main memory.

Geometry now inherits from GPUResource, which means that it requires access to Domain and the creation of a Geometry object registers into the resource manager. To preserve resources, either create the Geometry object beforehand, or create it as-needed and keep it indefinitely, instead of allocating it from stack.

Kanzi still supports rendering using flat vertex data, but this is not recommended because the Kanzi WebGL port does not support it.

This change simplifies the Geometry interface and removes variations of the class. The change removes these headers:

  • kanzi/core.ui/graphics2d/geometry_frame.hpp

  • kanzi/core.ui/graphics2d/geometry_quad.hpp

  • kanzi/core.ui/graphics_backend/gl/geometry_frame.hpp

  • kanzi/core.ui/graphics_backend/gl/geometry_gl.hpp

  • kanzi/core.ui/graphics_backend/gl/geometry_quad.hpp

  • kanzi/core.ui/graphics_backend/nogl/geometry_frame.hpp

  • kanzi/core.ui/graphics_backend/nogl/geometry_quad.hpp

  • kanzi/core.ui/graphics_backend/spansion/geometry_frame.hpp

  • kanzi/core.ui/graphics_backend/spansion/geometry_quad.hpp

Use the kanzi/core.ui/graphics2d/geometry.hpp instead.

Changes in Kanzi Android framework (droidfw)

  • Removed the handleVisibilityChanged method from the KanziSurfaceView and KanziTextureView views. Kanzi Android framework (droidfw) now tracks the effective user-visibility of each connected view, and skips the rendering of the hidden views. See Handling the user-visibility of views.

  • Added a required Surface argument to the KanziViewAdapter.handleSurfaceChanged method.

    Kanzi 3.9.3

    Kanzi 3.9.4

    void handleSurfaceChanged(int width, int height)

    void handleSurfaceChanged(Surface surface, int width, int height)

Changes to focus handling

  • Kanzi no longer tries to set keyboard focus to an activating Activity when there is no application focus. To control whether to set focus to an activating Activity:

    • In an Activity in a Parallel Activity Host set the Focus On Activation (ParallelActivityHostConcept::FocusOnActivationProperty) property.

    • In an Exclusive Activity Host set the Focus On Activating Activity (ExclusiveActivityHostConcept::FocusOnActivatingActivityProperty) property.

    See Controlling whether to set focus to an activating Activity.

  • Deprecated these functions:

    • FocusManager::isFocusScope() and FocusManager::isFocusFence().

      Use FocusManager::getFocusScopeType() instead.

    • FocusManager::setFocusScope() and FocusManager::setFocusFence().

      Use FocusManager::setFocusScopeType() instead.

Removal of explicit extract pass

Kanzi now automatically performs during the layout pass the functionality that was in previous versions handled by an explicit extract pass. This means that Kanzi no longer iterates through the node tree twice.

The improvement introduces the changes in the Node2D and Node3D classes:

  • Renamed the onExtract() callback to onTransform().

  • Removed the extract() function. Calling extract() right after layout() is no longer needed.

  • Added the transform() function for forcing the retransformation of a scene.

Changes to primitive mesh creation functions

Kanzi now supports setting the tessellation level of a primitive mesh. This improvement introduces the subdivisions parameter to the Mesh::createBox and Mesh::createPlane functions.

Kanzi 3.9.3

Kanzi 3.9.4

MeshSharedPtr createBox(Domain* domain, Vector3 size, string_view name, MaterialSharedPtr material = MaterialSharedPtr());

MeshSharedPtr createBox(Domain* domain, Vector3 size, unsigned int subdivisions, string_view name, MaterialSharedPtr material = MaterialSharedPtr());

MeshSharedPtr createPlane(Domain* domain, float width, float height, bool invertU, bool invertV, string_view name, MaterialSharedPtr material = MaterialSharedPtr());

MeshSharedPtr createPlane(Domain* domain, float width, float height, unsigned int subdivisions, bool invertU, bool invertV, string_view name, MaterialSharedPtr material = MaterialSharedPtr());

Changes to C++ Code Behind

This change is required only for projects that you created with Kanzi version 3.9.3.

In the <Project Name>/Application/CMakeLists.txt file change

set(CodeBehind_lib_dir "${CMAKE_CURRENT_SOURCE_DIR}/../Tool_project/CodeBehind")

to

set(CodeBehind_lib_dir "${CMAKE_CURRENT_SOURCE_DIR}/../Tool_project/CodeBehind/<Project Name>")