Kanzi 3.9 alpha 1 migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.8 to Kanzi 3.9.

Changes related to the 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.

Changes to the 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 Feature improvements.

Changes to the 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.

Changes to

the 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.

Changes to render passes

Introduced the GatherLightsRenderPass and GatherNearestLightsRenderPass render passes. Use these render passes 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 or GatherNearestLightsRenderPass 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 to the 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.

Other changes

• 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 overriden 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

• Reworked filters. This table shows the difference in filter classes between Kanzi 3.8 and 3.9.

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

See also

Kanzi 3.9 alpha 1 release notes

Known issues