Kanzi 3.6 migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.5 to Kanzi 3.6.

Directory structure for headers

Kanzi 3.6 introduces changes in the <KanziWorkspace>/Engine directory structure. To migrate your Kanzi application from Kanzi 3.5 to Kanzi 3.6, update the include paths in your application code.

For example, if your application uses kzs_file_base.h, v8_module.hpp, and gl_graphics_output.hpp headers, change

#include <system/file/kzs_file_base.h>
#include <kanzi/v8_module.hpp>
#include <kanzi/graphics_backend/gl_graphics_output.hpp>

to

#include <kanzi/core/legacy/file/kzs_file_base.hpp>
#include <kanzi/js/module.hpp>
#include <kanzi/core.ui/platform/graphics_backend/gl/gl_graphics_output.hpp>

These tables show the difference in the directory structure between Kanzi 3.5 and 3.6.

Kanzi 3.5

Description

Engine/include/application_framework

Contains the platform-specific application headers.

Engine/include/core

Contains the utilities, memory management, and data structures headers.

Engine/include/kanzi_components

Contains the Kanzi UI components headers.

Engine/include/kanzi_v8

Contains the headers for the JavaScript support.

Engine/include/system

Contains the native platform abstraction and graphics system initialization headers.

Engine/include/user

Contains the application logic and subsystems headers.

Kanzi 3.6

Description

Engine/include/kanzi/core

Combines the content of the non-graphics part of these Kanzi 3.5 directories:

  • include/core

  • Engine/include/system

  • Engine/include/user

Engine/include/kanzi/core/legacy

Contains the content of these Kanzi 3.5 directories and is going to be removed in the upcoming versions of Kanzi:

  • Engine/include/system

  • Engine/include/core

Engine/include/kanzi/core.ui

Contains the base subsystems of UI functionality that form the base for all UI controls and UI components. For example, this includes the input, rendering, and layout functionality. Combines the content of the graphics parts of these Kanzi 3.5 directories:

  • include/core

  • Engine/include/system

  • Engine/include/user

Engine/include/kanzi/js

Contains the headers for the JavaScript support. Replaces the Kanzi 3.5 directory Engine/include/kanzi_v8.

Engine/include/kanzi/ui

Contains the headers for the Kanzi UI components. Replaces the Kanzi 3.5 directory Engine/include/kanzi_components.

Preprocessor defines

If you created your own makefiles or build scripts to build your Kanzi applications, to build Kanzi applications using Kanzi 3.6, update these files to include the KANZI_FEATURE_3D preprocessor define.

Logging

Kanzi 3.6 introduces changes to the logging system. The logging system has a new type-safe format syntax and introduces the log level and log category to implement message classification and filtering. The log category allows you to filter messages for each category and filter the messages at compile-time.

The logging headers are now in the directory Engine/include/kanzi/core/log. To write messages to the log, use the logging macros, and set the log level and category for the log messages. In Kanzi 3.6 you can no longer print log messages to the application window but only to the debug console and the application configuration function logVisualizationEnabled() is no longer available.

This example shows the migration of common logging functionality from Kanzi 3.5 to Kanzi 3.6

// Define a new log category in a header file.
// For example, to define a log category called Texture.
#define TEXTURE_LOG_CATEGORY KZ_LOG_CREATE_CATEGORY(KZ_LOG_ENABLED_CATEGORY, "Texture")

// Error log.
// In Kanzi 3.5
// kzsLog(KZS_LOG_LEVEL_INFO, "Texture loaded.");
// In Kanzi 3.6
kzLogInfo(TEXTURE_LOG_CATEGORY, ("Texture loaded."));

// Formatted text.
// In Kanzi 3.5
// kzsLogFormat(KZS_LOG_LEVEL_INFO, ("Texture size %4dx%4d", 400, 600));
// In Kanzi 3.6
kzLogInfo(TEXTURE_LOG_CATEGORY, ("Texture size {:4}x{:4}.", 400, 600));

// Assign test log message to the Generic log category.
// In Kanzi 3.5
// kzsLog(KZS_LOG_LEVEL_WARNING, "Test warning message.");
// In Kanzi 3.6
kzLogWarning(KZ_LOG_CATEGORY_GENERIC, ("Test warning message."));

// In Kanzi 3.6 the type of the argument is deduced at compile-time so that you do not have to set it.
// In Kanzi 3.5
// kzsLogFormat(KZS_LOG_LEVEL_INFO, ("Test different formatting: %+04d %#x %12.15f %-+12.15g", 1, 2, 0.1, 0.5));
// In Kanzi 3.6
kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Test different formatting: {:+04} {:#x} {:12.15} {:<+12.15} ", 1, 2, 0.1, 0.5));

See log.hpp.

Rendering

Kanzi 3.6 introduces changes to rendering:

  • The class hierarchy for the RenderPass class changed:

    • The Kanzi 3.5 RenderPass class is called in Kanzi 3.6 LegacyRenderPass.

    • The Kanzi 3.5 Composer class is called in Kanzi 3.6 RenderPass. If you define your own render pass you must derive from the RenderPass class.

  • If you create your own render pass, the RenderPass::renderOverride() function replaced the Kanzi 3.5 virtual function applyOverride().

Kanzi Engine plugins

Defining property types

In Kanzi 3.6 the flags for defining property types in Kanzi Engine plugins are renamed.

Kanzi 3.5

Kanzi 3.6

KZU_PROPERTY_TYPE_CHANGE_FLAG_FINAL_TRANSFORMATION

PropertyTypeChangeFlagFinalTransformation

KZU_PROPERTY_TYPE_CHANGE_FLAG_MEASURE

PropertyTypeChangeFlagMeasure

KZU_PROPERTY_TYPE_CHANGE_FLAG_PARENT_MEASURE

PropertyTypeChangeFlagParentMeasure

KZU_PROPERTY_TYPE_CHANGE_FLAG_ARRANGE

PropertyTypeChangeFlagArrange

KZU_PROPERTY_TYPE_CHANGE_FLAG_RENDER

PropertyTypeChangeFlagRender

KZU_PROPERTY_TYPE_CHANGE_FLAG_DRAW

PropertyTypeChangeFlagDraw

KZU_PROPERTY_TYPE_CHANGE_FLAG_CONSTRAINT

PropertyTypeChangeFlagConstraint

Editor metadata

Kanzi 3.6 introduces changes to the way you declare the editor metadata for components you create in a Kanzi Engine plugin.

For example, in Kanzi 3.5, to create a custom property type VideoFileNameProperty for a custom node VideoView2D, you used

PropertyType<string> VideoView2D::VideoFileNameProperty(KZ_PROPERTY_TYPE_EDITOR_INFO([]() -> kanzi::PropertyTypeEditorInfo::AttributeDictionary { kanzi::PropertyTypeEditorInfo::AttributeDictionary dict;
    dict["DisplayName"] = "Video Filename";
    dict["Tooltip"] = "Video file to be played";
    dict["Host"] = "VideoView2D:freq";
    return dict; }()), kzMakeFixedString("VideoView2D.VideoFileName"), "", 0, false);

In Kanzi 3.6, to create the same custom property type, use

PropertyType<string> VideoView2D::VideoFileNameProperty(kzMakeFixedString("VideoView2D.VideoFileName"), "", 0, false,
                                                        KZ_DECLARE_EDITOR_METADATA
                                                        (
                                                            metadata.displayName = "Video Filename";
                                                            metadata.tooltip = "Video file to be played";
                                                            metadata.host = "VideoView2D:freq";
                                                        ));

This table shows the difference in declaring Kanzi Engine plugin editor metadata between Kanzi 3.5 and 3.6.

Kanzi 3.5

Kanzi 3.6

dict["Category"]

metadata.category

dict["DefaultValue"]

metadata["DefaultValue"]

dict["DisplayName"]

metadata.displayName

dict["Editor"]

metadata.editor

dict["Host"]

metadata.host

dict["LowerBound"]

metadata["LowerBound"]

dict["Step"]

metadata["Step"]

dict["UpperBound"]

metadata["UpperBound"]

dict["Tooltip"]

metadata.tooltip

dict["Type"] = "Enum";dict["Options"] = "string1|int1;string2|int2;...;stringN|intN";

metadata.valueProvider = "Enum:string1|int1;string2|int2;...;stringN|intN";

dict["Type"] = "ProjectObject";dict["TargetType"] = "value";

metadata.valueProvider = "ProjectObject:value";

dict["Type"] = "PropertyType";

metadata.valueProvider = "PropertyType";

dict["Type"] = "StringList";

metadata.valueProvider = "StringList";

All fields available in Kanzi 3.5 that are not listed here are taken from the metadata standard fields of the property type itself.

See Extending the functionality of Kanzi Engine and Reference for showing Kanzi Engine plugin custom types in Kanzi Studio.

Triggers and actions

In Kanzi 3.6 triggers are defined in the Trigger class and animation players in the AnimationPlayer class. Both classes derive from the NodeComponent class. In Kanzi 3.5 the AnimationPlayer class derived from the Trigger class.

Preload Resources action and On Preloading of Resources Completed trigger

The Preload Resources action and On Preloading of Resources Completed trigger are no longer available. Use the Prefab View node to load resources asynchronously during runtime. See Using node prefabs.

To load resources asynchronously during application runtime using the Kanzi Engine API, use ResourceManager::acquireResourcesAsync and Node::acquireResourceAsync. In the Kanzi Engine API see the collect_resource_urls.hpp file.

When you open a project created with an earlier version of Kanzi Studio which contains Preload Resources actions or On Preloading of Resources Completed triggers, Kanzi Studio 3.6 deletes these actions and triggers.

Play Animation action

The Play Animation action is no longer available. Use the animation players and actions instead. See Kanzi 3.5 migration guide.

Property namespaces

In Kanzi Studio 3.6 folders in the Library > Property Types show the property type namespace hierarchy.

When you open a project created with an earlier version of Kanzi Studio which contains folders in the Library > Property Types, Kanzi Studio 3.6 deletes these folders and places the property types in the Library > Property Types root.

Editing attributes of meshes

When you open your Kanzi Studio project, Kanzi Studio modifies the mesh data for the meshes included in the project:

  • Kanzi Studio converts the Kanzi Studio 3.5 mesh attribute mappings to the style used by Kanzi Studio 3.6. The 3.5 style mappings have mesh and shader attribute name pairs. In addition to this, the 3.6 style includes the semantic and semantic index fields. The converter tries to map the mesh attributes to the shader attributes matching the semantic and semantic index fields. Kanzi Studio writes to the KanziStudio.log warnings it encounters during this conversion.

  • Mesh attributes now contain the export semantics and export semantic index. If the export attributes are not set during this conversion, Kanzi Studio copies the export semantics from the import semantics and arranges the semantic index.

To see a full list of modifications to the mesh attribute mappings that Kanzi Studio made, open the Kanzi Studio log file after you open a project created in an earlier version of Kanzi Studio. You can find the Kanzi Studio log in %USERPROFILE%\AppData\Local\Temp\KanziStudioLogs\KanziStudio.log. See

You can now edit the attributes of meshes using the Mesh Attributes Editor. The Mesh Attributes Editor replaces the mapping mesh attributes used in earlier versions of Kanzi. See Optimizing meshes.

../../_images/mesh-attributes-editor.png

Application idle state

Kanzi now detects when there are no changes and stops rendering. If in your Kanzi application you use in shaders custom property types that you declared using the Kanzi Engine API or you created them in Kanzi Studio, make sure that these property types have the Affect Rendering property enabled. See Application idle state.

API renames

  • getProperty function changed from

    bool getProperty(PropertyType propertyType, DataType& value)

    to

    optional<DataType> getOptionalProperty(PropertyType propertyType)

  • setTrajectoryResourceID function changed from

    setTrajectoryResourceID(ResourceID("MyTrajectory"));

    to

    setTrajectory(trajectory);

  • Removed TrajectoryListBox3D::setLoopAlongY and changed TrajectoryListBox3D::setLoopAlongX to from TrajectoryListBox3D::setLooping.

  • Converted KzcVolume to C++ and renamed to Box.

  • Class Shader renamed to ShaderProgram.

  • VertexAttribute class divided into MeshVertexAttribute and ShaderVertexAttribute classes which both derive from the VertexAttribute base class.

  • Changed Texture::CreateInfo.

  • Texture::calculateMipmapLevelCount changed to calculateMipmapLevelCount.

  • The enum Usage moved from the Surface to the Framebuffer class.

  • Changed the callback signature for property notification handlers:

    • Changed the first parameter from Object to PropertyObject.

    • DataType specifies the data type of the property to which you subscribe. For example, use int, float, or any other supported data type.

    • Changed KzuPropertyNotificationReason to PropertyNotificationReason.

    Callback(PropertyObject& object, DataType& data, PropertyNotificationReason reason, void* userData)