Kanzi 3.9.0 migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.8.0 to Kanzi 3.9.0.

Removal of JavaScript functionality

Kanzi no longer includes the V8 JavaScript engine and Kanzi Studio no longer includes the Execute Script action, which enabled you to use JavaScript scripts in your Kanzi applications.

When you open in Kanzi 3.9.0 a Kanzi Studio project that uses Execute Script actions, Kanzi Studio marks nodes that use this action as invalid and marks them in red type, but does not remove them. This allows you to evaluate the functionality from those actions and their scripts, and manually replicate that functionality using other Kanzi features.

In your application code remove:

• #include <kanzi/js/module.hpp>

• V8Module::registerModule(domain);

64-bit Kanzi Studio Preview

Kanzi Studio Preview now uses 64-bit architecture. To migrate your Kanzi applications:

• Backup your Kanzi Studio project before you open it in Kanzi Studio 3.9.0. Kanzi Studio automatically updates the project in an irreversible way.

  If you have changed the default values for these items, you must manually migrate your Kanzi Studio project:

  • In Application/src/plugin/CMakeLists.txt change ${CMAKE_VS_PLATFORM_NAME} to Kanzi-specific ${PLATFORM_TARGET} that evaluates to Win64.

  • In Application/generate_cmake_vs2017_solution.bat add the -A x64 parameter.

    For example, change

    cmake -S . -B build_vs2017 -G "Visual Studio 15 2017"
    

    to

    cmake -S . -B build_vs2017 -G "Visual Studio 15 2017" -A x64
    

  • In Kanzi Studio in the Library > Kanzi Engine Plugins for each plugin in the Properties update the plugin path to the location of the 64-bit version of the Kanzi Engine plugin.

• Rebuild your Kanzi Engine plugins using 64-bit configuration and in a Kanzi Studio project that uses such plugins, in the Library > Kanzi Engine Plugins right-click each plugin and select Update Kanzi Engine Plugin.

Introduction of the MainLoopScheduler subsystem

• Removed classes SuspensionManager and FPSContraints. Still relevant features from these classes are now built into MainLoopScheduler.

• Removed the obsolete task scheduler implementations KzuTaskScheduler and Scheduler.

• Removed classes MainLoopTaskProfiler, MainLoopTaskSample, MainLoopTaskProfilerCategories, and MainLoopTaskProfileRegistry. Replaced with MainLoopProfiler and MainLoopProfilingSampleData.

• Removed classes Watermark and SplashScreen.

• Application class:

  • Moved enum State to MainLoopScheduler::State.

  • Renamed state Sleeping to Paused.

  • Removed states Uninitialized and Error.

  • Renamed sleep() to pause() and wakeup() to resume().

  • Removed onSleep(), onIdle(), and onWakeup().

  • Introduced onPause(), onResumeCheck() and onResume() that Kanzi calls on the entry into the Paused state, for each iteration of the paused loop and on exit from the Paused state respectively. Note that onPause() and onResume() are not equivalent to onSleep() and onWakeup(), which were in previous versions called directly inside sleep() and wakeup() calls. Neither is onResumeCheck() equivalent to onIdle(), and now holds the default implementation of checking the event queue for wake up event.

  • Removed runOverride(), updateOverride(), renderOverride(), suspendOverride(), yieldOverride(), sleepOverride(), and wakeupOverride().

  • Removed updateOverride(). Deprecated onUpdate(), but not yet removed. Prefer inserting tasks into the main loop in the User stage instead.

  • Removed onPreRender() and onPostRender(). Insert tasks before or after the Render stage instead.

  • Removed initializeWatermark() and initializeSplashScreen().

  • Removed getLastFrameTime() and getStopWatch(). Instead use MainLoopScheduler timing interface getLastFrameDuration().

  • Removed reloadProject().

  • Removed projectReloaded() and onProjectInitialized().

  • Renamed executePendingChanges() to loadStartupKzb().

  • Removed suspend(), yield(), idle(), and idleLoop(). This functionality is now implemented by the MainLoopScheduler.

Timer functionality

The Timer functionality is now part of the MainLoopScheduler subsystem and it replaces the removed Timer subsystem.

Now you add timer tasks directly into the main loop:

• To add a timer task before a stage, use MainLoopScheduler::prependTimer.

• To add a timer task after a stage, use MainLoopScheduler::appendTimer.

• To remove a timer, use MainLoopScheduler::removeTimer.

Timers now have these recurrence options:

• Kanzi executes the MainLoopScheduler::TimerRecurrence::OneTime timer tasks once when the specified time since their addition has elapsed.

• Kanzi executes the MainLoopScheduler::TimerRecurrence::Recurring timer tasks periodically at specified intervals. When multiple intervals have elapsed between the main loop iterations, Kanzi executes recurring tasks just once, but provides the repeat count through their callback interface.

Timers no longer use message arguments or properties, instead the timer callback directly receives elapsed duration rounded down to a multiple of the interval of the timer and number of elapsed intervals as arguments.

Performance HUD

Updated the Performance HUD to work with the MainLoopScheduler:

• Removed the show option from ApplicationProperties::profilingCategoryFilter.

• Introduced the application property PerformanceInfoProperties::graphFilter that is a semicolon-separated list of tasks for which profiling graphs to show in the Performance HUD.

Bindings

In the previous versions of Kanzi, if a binding used as a source value a property type that was not present in the source node, Kanzi did not apply that binding. Now when a property type is not present in the source node, bindings use the default value of that property type.

Resource manager

Modernized the ResourceManager ProtocolHandler signature:

• Instead of a function pointer, it now uses std::function.

• Removed the userdata argument. You can now capture additional state with the function, such as with lambda captures.

DataObject classes

DataObject classes no longer have public constructors. You must construct them using a static create function:

Kanzi 3.8.0	Kanzi 3.9.0
DataObject::DataObject(Domain*, string_view)	DataObject::create(Domain*, string_view)
DataObjectBool::DataObjectBool(Domain*, string_view)	DataObjectBool::create(Domain*, string_view)
DataObjectInt::DataObjectInt(Domain*, string_view)	DataObjectInt::create(Domain*, string_view)
DataObjectReal::DataObjectReal(Domain*, string_view)	DataObjectReal::create(Domain*, string_view)
DataObjectString::DataObjectString(Domain*, string_view)	DataObjectString::create(Domain*, string_view)

Color space

Introduced linear color workflow that is from now on the default color space. If you want to continue using the legacy color space (nonlinear gamma) in your application, in the application.cfg file for that application add:

SurfaceColorSpace = legacy

Note

On the linux_imx8_wayland_aarch64 platform Kanzi applications work only with the legacy color space.

See Color workflow and Surface properties.

Node class

• Removed the trailing / from the getRelativePath() returns. For example, instead of my/item/, the function now returns my/item.

• Added the leading / to the values of Node::PathProperty and the Node::getPath() returns so that they are valid absolute paths. For example, instead of Screen/RootPage, the value is now /Screen/RootPage.

Light nodes

Removed from Light nodes the Color Scale (Light::ColorScaleProperty) property. To adjust the brightness of a light, set the Intensity (I) of the light color property. See Adjusting the brightness of a light.

When you open your project in Kanzi Studio, Kanzi Studio automatically converts local values of light properties, but in some cases you have to adjust the lights manually after converting your project to Kanzi 3.9.0. For example, if your project contains a binding that binds a light color property to a custom property type, set the Editor of that custom property type to HDR color editor, then adjust the light color.

Activity system

If your application uses Activity or Activity Host nodes, the only way to migrate your application from Kanzi 3.8.0 to 3.9.0 is to recreate the Activity structure of your application.

Before you recreate the Activity structure, remove all existing Activity and Activity Host nodes form the Node Tree.

To learn how to use the Activity system:

• Complete the Activity system tutorials. See Activity system.

• Learn about the details of the Activity system. See Activity nodes.

API changes

Type	Kanzi 3.8.0	Kanzi 3.9.0
Class	CodeBehindBase	CodeBehind
Header file	code_behind_base.hpp	code_behind.hpp

Code Behind

When you open in Kanzi Studio the project of an application that uses Code Behind before you migrate the Code Behind functionality, the Kanzi Studio Preview cannot start.

To migrate an application that uses Code Behind:

1. In Kanzi Studio 3.9.0 open the project of the application that uses Code Behind, in the Library > Kanzi Engine Plugins select the Code Behind plugin (<ProjectName>_CodeBehind), and delete it.

2. Recreate the Activity structure of your application. See Activity system.

3. Readd Code Behind:

   1. In the Activity Browser right-click the Activity or Activity Host to which you want to add Code Behind and select Add Code Behind.

   2. Copy the Code Behind functionality that you created in Kanzi 3.8.0:

      • If your application is based on the Kanzi Studio project Kanzi Studio template, copy the functionality:

        • From <ProjectName>/CodeBehind/Application/include to <ProjectName>/CodeBehind/include

        • From <ProjectName>/CodeBehind/Application/source to <ProjectName>/CodeBehind/source

      • If your application is based on the Application, Application with data source plugin, or Application with Kanzi Engine plugin Kanzi Studio template, copy the functionality:

        • From <ProjectName>/Tool_project/CodeBehind/Application/include to <ProjectName>/Tool_project/CodeBehind/include

        • From and <ProjectName>/Tool_project/CodeBehind/Application/source to <ProjectName>/Tool_project/CodeBehind/source

      Keep in mind these changes in the Code Behind file naming convention.

      File purpose	Kanzi 3.8.0	Kanzi 3.9.0
      Module	<ProjectName>codebehind_module	<ProjectName>_code_behind_module
      Activity	<ActivityName>activitycode	<ProjectName>_<ActivityName>_activity_code
      Activity Host	<ActivityHostName>activitycode	<ProjectName>_<ActivityHostName>_activity_code

4. Delete the <ProjectName>CodeBehind/Application directory.

5. In Kanzi Studio restart the Preview.

See Programming Activity nodes with Code Behind.

Android Gradle Plugin and Gradle

To migrate Kanzi applications to use Android Gradle Plugin 4.2.2 and Gradle 6.7.1:

1. In Android Studio in the android_gradle/app/build.gradle file replace:

   externalNativeBuild {
       cmake {
           path "CMakeLists.txt"
       }
   }
   

   with

   externalNativeBuild {
       cmake {
           path "CMakeLists.txt"
       }
   }
   

2. In the android_gradle/build.gradle file replace:

   dependencies {
       classpath 'com.android.tools.build:gradle:<android-studio-version>'
       classpath 'com.rightware.gradle:kanzi:<gradle-plugin-version>'
   }
   

   with

   dependencies {
       classpath 'com.android.tools.build:gradle:4.2.2'
       classpath 'com.rightware.gradle:kanzi:0.6.2'
   }
   

3. In the android_gradle/gradle/wrapper/gradle-wrapper.properties file replace:

   distributionUrl=https\://services.gradle.org/distributions/gradle-<version>-bin.zip
   

   with

   distributionUrl=https\://services.gradle.org/distributions/gradle-6.7.1-bin.zip
   

4. In the android_gradle/gradle.properties file replace:

   org.gradle.jvmargs=-Xmx<size>m
   

   with

   org.gradle.jvmargs=-Xmx4608m
   

5. To update Gradle in your application, either:

   • In Android Studio select Gradle > Task > build setup > Wrapper.

   • On the command line run:

     ./gradlew wrapper
     

Render passes

Changes related to collecting Light nodes

Introduced the GatherLightsRenderPass. Use this render pass to collect Light nodes for lighting 3D nodes in a scene.

If your application contains render passes that draw nodes using lights, you must add a GatherLightsRenderPass that collects the lights. DrawObjectsRenderPass and DrawObjectsWithMaterialRenderPass no longer collect lights.

For example, in

RenderPassTemplateSharedPtr clearTemplate = RenderPassTemplate::create(CompositionTargetRenderPass::getStaticMetaclass()->getName(), "clear");
        RenderPassTemplateSharedPtr drawTemplate = RenderPassTemplate::create(DrawObjectsRenderPass::getStaticMetaclass()->getName(), "draw");
        RenderPassTemplateSharedPtr groupTemplate = RenderPassTemplate::create(RenderPass::getStaticMetaclass()->getName(), "group");
        groupTemplate->addChild(clearTemplate);
        groupTemplate->addChild(drawTemplate);
        RenderPassPrefabSharedPtr renderPassPrefab = RenderPassPrefab::create(domain, "Render Pass Prefab", groupTemplate);

add a GatherLightsRenderPass as a parent of the DrawObjectsRenderPass:

RenderPassTemplateSharedPtr clearTemplate = RenderPassTemplate::create(CompositionTargetRenderPass::getStaticMetaclass()->getName(), "clear");
        RenderPassTemplateSharedPtr drawTemplate = RenderPassTemplate::create(DrawObjectsRenderPass::getStaticMetaclass()->getName(), "draw");
        RenderPassTemplateSharedPtr gatherLightsTemplate = RenderPassTemplate::create(GatherLightsRenderPass::getStaticMetaclass()->getName(), "gatherLights");
        RenderPassTemplateSharedPtr groupTemplate = RenderPassTemplate::create(RenderPass::getStaticMetaclass()->getName(), "group");
        groupTemplate->addChild(clearTemplate);
        groupTemplate->addChild(gatherLightsTemplate);
        gatherLightsTemplate->addChild(drawTemplate);
        RenderPassPrefabSharedPtr renderPassPrefab = RenderPassPrefab::create(domain, "Render Pass Prefab", groupTemplate);

Changes related to multiple render target rendering

The CompositionTargetRenderPass now supports rendering to multiple composition targets.

This table shows the renamed and added properties.

Kanzi 3.8.0	Kanzi 3.9.0
ClearRenderPass::ClearColorProperty	ClearRenderPass::ClearColor0Property
Not available	ClearRenderPass::ClearColor1Property
Not available	ClearRenderPass::ClearColor2Property
Not available	ClearRenderPass::ClearColor3Property
CompositionTargetRenderPass::CompositionTargetProperty	CompositionTargetRenderPass::CompositionTarget0Property
Not available	CompositionTargetRenderPass::CompositionTarget1Property
Not available	CompositionTargetRenderPass::CompositionTarget2Property
Not available	CompositionTargetRenderPass::CompositionTarget3Property
CompositionTargetRenderPass::PixelFormatProperty	CompositionTargetRenderPass::PixelFormat0Property
Not available	CompositionTargetRenderPass::PixelFormat1Property
Not available	CompositionTargetRenderPass::PixelFormat2Property
Not available	CompositionTargetRenderPass::PixelFormat3Property
CompositionTargetRenderPass::ResultTextureProperty	CompositionTargetRenderPass::ResultTexture0Property
Not available	CompositionTargetRenderPass::ResultTexture1Property
Not available	CompositionTargetRenderPass::ResultTexture2Property
Not available	CompositionTargetRenderPass::ResultTexture3Property

This table shows the renamed functions.

Kanzi 3.8.0	Kanzi 3.9.0
ClearRenderPass::getClearColor()	ClearRenderPass::getClearColor0()
ClearRenderPass::setClearColor()	ClearRenderPass::setClearColor0()
CompositionTargetRenderPass::getCompositionTarget()	CompositionTargetRenderPass::getCompositionTarget0()
CompositionTargetRenderPass::setCompositionTarget()	CompositionTargetRenderPass::setCompositionTarget0()
CompositionTargetRenderPass::getPixelFormat()	CompositionTargetRenderPass::getPixelFormat0()
CompositionTargetRenderPass::setPixelFormat()	CompositionTargetRenderPass::setPixelFormat0()
CompositionTargetRenderPass::getResultTexture()	CompositionTargetRenderPass::getResultTexture0()
CompositionTargetRenderPass::setResultTexture()	CompositionTargetRenderPass::setResultTexture0()

Filters

Reworked filters.

This table shows the difference in filter classes between Kanzi 3.8.0 and 3.9.0.

Kanzi 3.8.0	Kanzi 3.9.0
KzuObjectSource	ObjectSource
KzuSortObjectSource	SortObjectSource
KzuCombinerObjectSource	CombinerObjectSource
KzuFilterObjectSource	FilterObjectSource
KzuContainsPropertyFilter	ContainsPropertyFilter
KzuFrustumCullFilter	FrustumCullFilter
KzuLODFilter	removed
KzuObjectTypeFilter	ObjectTypeFilter
KzuPropertyIsEqualFilter	PropertyIsEqualFilter
KzuTagFilter	TagFilter

Instantiator node

Refactored the Instantiator node. The Instantiator node no longer preserves the local transformation of the node that it instantiates. The instantiation now happens from the instantiated node onwards. See Using the Instantiator node.

To migrate your project to Kanzi 3.9, you may need to move the transformation from the instantiated node to the Instantiator node or add a parent node that you instantiate instead.

Text rendering

Introduced the TextConcept base class for nodes that implement text rendering (TextBlock2D, TextBlock3D, TextBox2D, TextBox3D).

Moved to TextConcept these properties that are common to all nodes that implement text rendering:

Kanzi 3.8.0	Kanzi 3.9.0
TextBlockConcept::FontColorProperty	TextConcept::FontColorProperty
TextBlockConcept::FontMaterialProperty	TextConcept::FontMaterialProperty
TextBlockConcept::HorizontalPaddingProperty	TextConcept::HorizontalPaddingProperty
TextBlockConcept::RemoveSideBearingsProperty	TextConcept::RemoveSideBearingsProperty
TextBlockConcept::TextProperty	TextConcept::TextProperty
TextBlockConcept::TextHorizontalAlignmentProperty	TextConcept::TextHorizontalAlignmentProperty
TextBlockConcept::TextVerticalAlignmentProperty	TextConcept::TextVerticalAlignmentProperty
TextBlockConcept::VerticalPaddingProperty	TextConcept::VerticalPaddingProperty
TextBlockConcept::OverflowProperty	TextConcept::OverflowProperty

Input and focus handling

• Moved the key press repetition functionality from KeyRepeatConcept and KeyRepeatConceptImpl<> to the KeyRepeatGenerator.

• Moved the functionality of the KeyInputConcept, KeyInputConceptImpl<>, and KeyInputGestureDetector<> to the InputManipulator.

• Removed the Enter key handling messages InputMethod::pressEnterKey, InputMethod::releaseEnterKey, InputMethod::cancelEnterKey, TextBoxConcept::EnterKeyPressedMessage, TextBoxConcept::EnterKeyReleasedMessage, TextBoxConcept::EnterKeyCanceledMessage, TextInputManipulator::EnterKeyPressedMessage, TextInputManipulator::EnterKeyReleasedMessage, and TextInputManipulator::EnterKeyCanceledMessage.

• Introduced input method action handling messages TextBoxConcept::InputMethodActionMessage, TextBoxConcept::InputMethodAvailableMessage, and TextBoxConcept::InputMethodUnavailableMessage.

• Removed the FocusManager::PreFocusMessageArguments::AcceptFocusProperty from the message arguments. To decide whether you can move focus to a node, use the focus scope types and the properties related to the focus management. To limit the focus chain navigation in a node tree, attach the Focus Scope Type property to your node and set its value to Fence, Modal or Popup.

• Deprecated the Logical Focus property (FocusManager::LogicalFocusProperty).

  Kanzi Studio automatically converts projects that use the Logical Focus property by replacing the Logical Focus property with the Focus Order property set to 0. This change sets a node that has the Focus Order property set to 0 as the first focusable node in the focus scope. See Moving focus in the focus chain.

• Removed from the FocusManager these properties and options related to directional navigation:

  • NextFocusNodePathProperty, PreviousFocusNodePathProperty, UpNavigationNodePathProperty, DownNavigationNodePathProperty, LeftNavigationNodePathProperty, and RightNavigationNodePathProperty properties.

  • FocusChainDirection options UpFocusable, DownFocusable, LeftFocusable, and RightFocusable.

  Use the Navigation Manipulator to implement directional navigation. See Using the Navigation Manipulator.

• Renamed or removed these FocusManager methods:

  Kanzi 3.8.0	Kanzi 3.9.0
  FocusManager::getActiveFocus()	FocusManager::getFocus()
  FocusManager::trySetActiveFocus()	FocusManager::trySetFocus()
  FocusManager::tryMoveActiveFocus()	FocusManager::tryMoveFocus()
  FocusManager::tryMoveActiveFocusForward()	FocusManager::tryMoveFocusForward()
  FocusManager::tryMoveActiveFocusBackward()	FocusManager::tryMoveFocusBackward()
  FocusManager::tryMoveActiveFocusUpward()	removed
  FocusManager::tryMoveActiveFocusDownward()	removed
  FocusManager::tryMoveActiveFocusLeft()	removed
  FocusManager::tryMoveActiveFocusRight()	removed

Scrolling functionality

• The Scroll View 2D and Grid List Box 2D nodes now by default scroll the same amount as the user drags the pointer. To migrate your project to Kanzi 3.9.0, in the Scroll View 2D and Grid List Box 2D nodes adjust the value of the Scroll Sensitivity property (ScrollViewConcept::SensitivityProperty, GridListBoxConcept::SensitivityProperty). The default value is 1. For example, to set the node to scroll twice the amount that the user drags the pointer, set the value of the Scroll Sensitivity property to 2.

  Kanzi 3.9.0 removes the unintended behavior caused by setting the Scroll Sensitivity property to a negative value. The Scroll Sensitivity property can no longer have a negative value. For example, to change the direction of scrolling in a Scroll View 2D node that you use to rotate a 3D model, modify the binding that binds the rotation to the scroll position. See Tutorial: Rotate a 3D model.

• In the Scroll View, Grid List Box, and Trajectory List Box 3D nodes the value of the Scroll Position property (ScrollViewConcept::ScrollPositionProperty, GridListBoxConcept::ScrollPositionProperty, TrajectoryListBox3D::ScrollPositionProperty) now decreases when the pointer moves right and down. To migrate your project to Kanzi 3.9.0, adjust the bindings and Set Property actions that target the scroll position of a Scroll View or List Box node. In some cases you must replace a Set Property action with a binding. For example, if you in an earlier version of Kanzi used the value of the Scroll Position property to set the translation of content in a Scroll View node, negate the value of the Scroll Position property. See Creating a Scroll View node.

• Deprecated the Scroll Axis property (ScrollViewConcept::ScrollAxisProperty).

  Kanzi Studio automatically converts projects that use the Scroll Axis property by replacing the Scroll Axis property with the Allowed Scroll Axis property.

• Refactored the messages that scroll Scroll View and Grid List Box nodes.

  Kanzi 3.8.0	Kanzi 3.9.0
  ScrollViewConcept::ScrollDirectionMessage	ScrollViewConcept::ScrollDownMessage ScrollViewConcept::ScrollUpMessage ScrollViewConcept::ScrollLeftMessage ScrollViewConcept::ScrollRightMessage
  ScrollViewConcept::ScrollEdgeMessage	ScrollViewConcept::ScrollHomeMessage ScrollViewConcept::ScrollEndMessage
  ScrollViewConcept::ScrollPageMessage	ScrollViewConcept::ScrollPageDownMessage ScrollViewConcept::ScrollPageUpMessage

ListBoxItemContainer prefabs

ListBoxItemContainer2D and ListBoxItemContainer3D now inherit from ContentLayout2D and ContentLayout3D.

2D node caching

Removed these properties:

• Cache Children (Node2D::CacheChildrenProperty)

  Kanzi no longer supports caching only the children of a node. To cache the descendants of a node without caching the node itself, move the child nodes to a separate node and in that node set the Caching Mode property to Enabled.

• Cache Result (Node2D::CacheResultProperty)

  Kanzi Studio automatically converts projects that use the Cache Result property by replacing it with the Caching Mode property.

• Cache Self (Node2D::CacheSelfProperty)

  Kanzi no longer supports caching a node but not caching the descendants of that node. To cache a node without caching its descendants, move the descendant nodes to a separate node, and in the node that you want to cache set the Caching Mode property to Enabled.

The caching system for 2D nodes now supports automatic cache refresh and invalidation. See Caching 2D nodes.

ForwardingAction class

Improved the ForwardingAction class to reduce the need for boilerplate code in derived classes:

• Look-up contexts of all binding runtimes are now automatically attached to the associated trigger. The derived classes no longer have to do this.

• Look-up contexts of all message binding runtimes are now automatically attached to the forwarded message of the associated trigger. The derived classes no longer have to do this.

In the release notes, see Other improvements.

Profiler category creation

To create a profiling category, you must now invoke an additional macro to initialize the profiling category. You must place this second macro into a cpp file. The new macro prevents re-registration of the category when you include it into multiple libraries that are dynamically loaded in the same application.

To create a profiling category, use both kzProfilingRegisterExportedCategory and kzProfilingInitializeCategory. kzProfilingRegisterExportedCategory can be in either an hpp or a cpp file. kzProfilingInitializeCategory must be used in a cpp file.

For an example on how to create a profiling category, see the code example for the kzProfilingRegisterExportedCategory in the Kanzi Engine API reference.

// Example export/import macro for Windows.
#ifdef USE_SHARED_LIBRARY
#ifdef COMPILE_LIBRARY_CODE
// Compiling shared library: export category to shared library.
#define EXPORT_IMPORT_API __declspec(dllexport)
#else
// Compiling user code: import category from shared library.
#define EXPORT_IMPORT_API __declspec(dllimport)
#endif
#else
// Use empty macro for static linking.
#define EXPORT_IMPORT_API
#endif

#define MY_PROFILING_CATEGORY_EXPORTED kzProfilingCreateCategory(KZ_PROFILING_ENABLED_CATEGORY, "myCategoryExported", KZ_PROFILING_DEFAULT_SAMPLE_BUFFER_SIZE)
kzProfilingRegisterExportedCategory(EXPORT_IMPORT_API, MY_PROFILING_CATEGORY_EXPORTED, KZ_PROFILING_DISABLED_CATEGORY)

// kzProfilingInitializeCategory must be placed in a cpp file.
kzProfilingInitializeCategory(EXPORT_IMPORT_API, MY_PROFILING_CATEGORY_EXPORTED, KZ_PROFILING_DISABLED_CATEGORY)

Application configuration

Graphics context and surface client APIs

Renamed these configuration settings and options that you use in the application.cfg:

Kanzi 3.8.0	Kanzi 3.9.0
GraphicsBackend	SurfaceClientAPI, GraphicsContextAPI
opengl	gl

Renamed these configuration settings and options that you use in the Application::onConfigure() function:

Kanzi 3.8.0	Kanzi 3.9.0
configuration.defaultSurfaceProperties.type	configuration.defaultSurfaceProperties.clientAPI
KZS_SURFACE_TYPE_GL_ONLY	SurfaceClientAPI::OpenGL
KZS_SURFACE_TYPE_GLES_ONLY	SurfaceClientAPI::OpenGLES
KZS_GRAPHICS_CONTEXT_API_WGL	GraphicsContextAPI::WGL
KZS_GRAPHICS_CONTEXT_API_EGL	GraphicsContextAPI::EGL
KZS_GRAPHICS_CONTEXT_API_GLX	GraphicsContextAPI::GLX

See Graphics library.

Buffer swap behavior

Renamed the configuration options that you use for buffer swap in the Application::onConfigure() function:

Kanzi 3.8.0	Kanzi 3.9.0
KZS_SWAP_BEHAVIOR_DONT_CARE	SwapBehavior::Unspecified
KZS_SWAP_BEHAVIOR_COPY	SwapBehavior::Copy
KZS_SWAP_BEHAVIOR_EXCHANGE	SwapBehavior::Exchange

See Surface properties.

Other changes

• Removed the deprecated Play Animation action. Use the Animation Player instead. See Using keyframe animations and Creating animations and timelines using the Kanzi Engine API.

• Changes in kanzi/core:

  • Moved ScopedRefCounter to kanzi/core/util/scoped_ref_counter.hpp.

  • Moved from_chars to kanzi/core/cpp/charconv.hpp.

  • Moved KZ_NOT_MOVABLE_NOT_COPYABLE and KZ_MOVABLE_BUT_NOT_COPYABLE to kanzi/core/util/macros.hpp.

  • Replaced kzArrayLength with size(array) defined in kanzi/core/cpp/iterator.hpp.

  • Imported std::move to the kanzi namespace.

  • Removed boost/move/utility.hpp inclusion.

  • Removed macros:

    • KZ_COPY_ASSIGN_REF

    • KZ_RV_REF

    • KZ_MOVE_RET

    • KZ_MOVE_BASE

    • KZ_USE_MOVE_EMULATION

• Replaced the KzuBoundingVolume and KzuTransformedBoundingVolume classes with Box and OrientedBoundingBox classes. If your class derives from Node and has overridden Node::getBoundingVolume virtual function, you must now implement the Node3D::getBoundingBox function. Renamed the related helper functions for rendering bounding boxes in Renderer3D.

• Moved ActionArgumentType to KzbMemoryParser::ArgumentType.

• Removed KzcHashMap and KzcHashSet. Use unordered_map and unordered_set instead.

• Removed KzcDynamicArray. Use vector instead.

• Removed KzcMemoryManager. Use vector, new/delete, new[]/delete[] instead.

• Removed kzsTimeGetCurrentTimestamp and kzsTimeGetCurrentTimeMicroseconds. Use kanzi::Clock or std::steady_clock instead.

• Removed obsolete internal bitmap image loading functions:

  • imageLoadPVRTC

  • imageLoadETC

  • imageLoadATC

  • imageLoadASTC

  • imageLoadRaw2D

• Moved task_dispatcher.hpp from kanzi/core.ui/scheduler to kanzi/core.ui/task_dispatcher.

• Replaced rayPickCalculateRay with Camera::calculateCameraRay.

See also

Kanzi 3.9.0 release notes

Known issues