Kanzi 4.1.2 release notes

Tracing

  • The trace of a Profiling or Debug build now shows the time that Kanzi Engine spends laying out 3D nodes and text. See Tracing.

    • Each time Kanzi Engine measures or arranges a 3D node, the trace shows a <node name> Node3D::measure or <node name> Node3D::arrange scope, like the <node name> Node2D::measure and <node name> Node2D::arrange scopes of 2D nodes.

    • Each time Kanzi Engine lays out text, the trace shows a TextLayouter::createLayout scope.

      Note

      The Performance HUD lays out its text in every frame, so the trace shows TextLayouter::createLayout scopes for it too. To trace only the text of your application, turn off the Performance HUD.

    Because of these scopes, a trace of an application that lays out many 3D nodes or text nodes in every frame fills the tracing memory faster. To keep the same number of frames in a trace, increase TracingSampleMaxMemory. See TracingSampleMaxMemory.

  • The trace of a Profiling or Debug build now shows a Resource count sample with the number of resources that the resource manager holds, next to the Resource CPU Memory (kb) and Resource GPU Memory (kb) samples.

3D node layout optimization

  • Kanzi Engine no longer recalculates the transformations of unchanged 3D nodes and their descendants when a sibling node lays out its content again. This applies to 3D nodes whose parent node does not lay out its child nodes, such as an Empty Node 3D or a Scene. For example, this makes updates faster when a data source changes the text of a few of many Text Block 3D nodes under the same Empty Node 3D.

3D node transformation optimization

  • Kanzi Engine now spends less CPU time updating the transformations of 3D nodes when a 3D node moves. For example, this makes it faster to pan a map whose tiles, roads, and labels are 3D nodes.

Focus optimization

  • Toggling the visibility of nodes is now faster in applications with many nodes. Before, each time the Visible property of a node changed, Kanzi Engine searched the node tree for the focused node. The search took longer the more nodes came before the focused node, such as the nodes of a large 3D scene in a Viewport 2D. Now Kanzi Engine searches only when you hide a focusable node or a focus scope node, or when hiding or showing a node changes which overlay scope has the focus. See FocusManager.

Property system optimization

  • Reading and setting the properties of nodes and other Kanzi objects is now faster. Kanzi Engine now finds the storage of a property faster, and only once each time it reads a property. This changes the size of PropertyObject and of every class that derives from it, so rebuild your Kanzi Engine plugins and applications against Kanzi 4.1.2.

    See Kanzi 4.1.2 migration guide.

Text layout optimization

  • With the FreeType font engine, which is the default, Kanzi Engine now spends less CPU time laying out text, for example each time a data source changes the text of a text node, or when text uses a Font Size that its font file used before. See FontEngine.

  • Kanzi Engine now spends less time laying out a Text Block 2D or Text Block 3D node that its parent lays out again. When no property that affects the layout of that node changed, Kanzi Engine no longer checks whether the node needs a new text layout. This applies when the node does not use Word Wrap, Overflow, or Truncation.

    Because of this, Kanzi Engine calls TextBlockConceptImpl::onPostPrepareTextFormat fewer times. When no such property changed, Kanzi Engine does not call it. When one changed, Kanzi Engine calls it once in each layout pass instead of two or three times. If your Text Block class changes the text or font properties of the node in that function, the node keeps its previous text layout. Make such changes outside the layout, for example in a main loop task.

    Note

    A Text Block node keeps its previous text layout and size when your application removes or replaces the state manager that sets its text or font properties. The same happens when your application renames the target node of a state object. To update the node, call Node::invalidateMeasure on it. In the Preview, this can also happen when you remove a text or font property from a state. To update the Preview, restart it.

Text rendering optimization

  • Kanzi Engine now renders a Text Block 3D node faster when its text has no colored glyphs, such as emoji. For such text, Kanzi Engine skips rendering with the Color Font Material. See Color fonts.

  • With Vulkan, Kanzi Engine now spends less time when it first renders text with a font file at a Font Size that it has not used before. To clear the new glyph cache texture for that font size, Kanzi Engine now uses the GPU instead of uploading a texture of zeros.

  • Kanzi Engine now spends less CPU time preparing text for rendering when the text moves or scales inside its node, but the text itself stays the same. Kanzi Engine reuses the rendering data of the text instead of creating it again. For example, this applies when:

    • You change the alignment or padding of a Text Block or Text Box node.

    • Horizontal Fit scales text to a new width.

    • The user scrolls the text of a Text Box node by moving the cursor.

    Each time Kanzi Engine creates the rendering data of a text, the trace of a Profiling or Debug build shows a TextFormat::createGlyphRuns scope. See Tracing.

    Note

    The Performance HUD creates the rendering data of its text in every frame, so the trace shows TextFormat::createGlyphRuns scopes for it too. To trace only the text of your application, turn off the Performance HUD.

Rendering

  • You can now render a 2D node to a Render Target Texture whose Format is Alpha 8-bit (A8_UNORM), by setting the texture as the Render Target property of the node. Kanzi Engine writes the red component of the fragment shader output to the texture, and shaders read that value as alpha. A Composition Target render pass still discards such a texture with a warning. For a multisampled render target texture and on WebGL, Kanzi Engine still logs a warning and skips the framebuffer attachments.

Kanzi Engine C++ API

Documentation

  • Added a description of what happens to the tasks that you submit to the TaskDispatcher while no Kanzi view is active in Kanzi Android framework (droidfw). These tasks wait, and Kanzi executes all of them in the first frame after a view becomes active again. An application that submits a task for each update of a data source while no view is active can delay that first frame by seconds. The documentation describes how to keep tasks from piling up. See Submitting tasks while no view is active.

  • Added a description of the Kanzi Portal MCP server, which connects your AI assistant to your Kanzi Account, so that you can query and manage your licenses, organizations, downloads, and support tickets. See Kanzi Portal MCP server. Also added a quick setup for the Kanzi MCP servers to Using Kanzi AI tools.

  • The Kanzi documentation is now also available in Simplified Chinese and Japanese. The translations are made with AI, and the English documentation is the authoritative version. Every translated page states this and links to the same page in English. The API references, the generated references, such as the node and resource reference, and the license texts are in English, and the translated pages link to the English API reference.

Notable fixes

Kanzi Engine

  • Fixed the issue where memory use grew each time Kanzi attached a binding to a node or resource that stayed alive between attachments. Kanzi 4.0.0 introduced the issue. (FMW-1643)

    This happened, for example, when:

    • An application detached a node and attached it again.

    • The data context of a node with a data source binding changed.

    • An application re-created prefab instances that bind to a node, data object, or material outside the instance.

  • Fixed the issue where Kanzi Engine wrote a trace file that was not valid JSON when the trace held no events, for example when the application wrote the trace right after clearing it. Trace viewers such as Chrome tracing and Perfetto could not load such a file. (FMW-1690)

  • Fixed the issue where, with the FreeType font engine, FreeTypeFontFile::setSize threw an exception only the first time for a font size that FreeType rejects. After that, Kanzi Engine laid out text at that size incorrectly without an exception, for example with TextLayouter. (FMW-1753)

  • Fixed the issue where Kanzi Engine created a separate EGL context for each window surface. This increased driver memory use, for example on Qualcomm Adreno GPUs. Kanzi Engine now uses one EGL context for all window surfaces. Kanzi 4.1.0 introduced the issue. (RENDERING-3483)

  • Fixed the issue where native and GPU memory use grew each time an application destroyed and created Kanzi Engine again. This happened, for example, when an Android application recreated its Kanzi view. Kanzi Engine now destroys its EGL contexts at shutdown. Kanzi 4.1.0 introduced the issue. (INTE-1336)

  • Fixed the issue that caused an application that uses OpenGL to terminate on Qualcomm Adreno GPUs after it destroyed a resource set that uses texel buffer textures, for example when the application switches between particle effects. (RENDERING-3556)

  • Fixed the issue where application code that uses the kzTraceInstant macro did not compile in a build without tracing, such as a Release build. (FMW-1683)

Kanzi Android framework (droidfw)

  • Fixed the issue that caused a native window leak each time a Kanzi Android framework (droidfw)-based view received a surface change that changed neither the surface nor its size. Such a change follows each creation of the surface of a KanziSurfaceView or a Kanzi Android Service client view, for example when the device rotates. Kanzi 4.0.0 introduced the issue. (ANDROID-2243)

  • Fixed the issue where a Kanzi Android framework (droidfw)-based view terminated the application when the view received an orientation change or a surface destroy while it had no surface. In the Kanzi Android Service host, this terminated every client application of the host. (ANDROID-2262)

    This happened, for example, when:

    • The application forwarded onConfigurationChanged to a view that had not received its surface yet or had lost it in the background.

    • The surface of a Kanzi Android Service client arrived during a cross-application transition before the overlay surface.

Kanzi Android Service

  • Fixed the issue where the Kanzi Android Service host terminated repeatedly after it restarted while a client application was in the background. Client applications no longer terminate when the Kanzi Android Service host restarts. They reconnect to the restarted Kanzi Android Service host, which loads their content again. Data that a client application pushed before the restart is lost, so push it again in onServiceConnected. (ANDROID-2256)

  • Fixed the issue where the Kanzi Android Service host terminated repeatedly after it restarted while a KanziServiceSurfaceView or KanziServiceComposable client was on the screen. Android then stopped restarting the Kanzi Android Service host for 30 minutes. (ANDROID-2268)

  • Fixed the issue where a debug build of the Kanzi Android Service host terminated when another client application lost its window after the host had preloaded a client prefab. For a preloaded client application, KanziServiceViewAdapterListener.onAttachedToWindow now fires when its client view attaches to a window, and no longer during preloading. (ANDROID-2206)

    After its prefab loads, a preloaded client view is no longer active, so tasks that the Kanzi Android Service host application submits to the task dispatcher wait until a client view becomes active. See Submitting tasks while no client view is active.

  • Fixed the issue where a cross-application transition sometimes did not end. The transition overlay stayed on the screen, and Kanzi Android Service ignored the later window and surface events of that client application. The transition now also ends when the user leaves the client application before the transition ends, or when the target client application never shows its view. See Setting up cross-application transition animations. (ANDROID-2245)

    KanziServiceTextureView does not support cross-application transitions, because a TextureView has no SurfaceControl. startSeamlessTransition of a KanziServiceTextureView now throws UnsupportedOperationException instead of starting a transition that never ends.

  • Fixed the issue where a KanziServiceSurfaceView, KanziServiceTextureView, or KanziServiceComposable that you removed from its window, added back, and removed again terminated the client application. A view that you added back also stayed empty. For example, this happened with fragments, ViewPager, RecyclerView, and LazyColumn. A client view now connects to the Kanzi Android Service when it attaches to a window, instead of when you inflate it or call connect, and disconnects when it detaches. KanziServiceClientListener.onServiceConnected now fires again each time the view re-attaches, and the client drops the calls that you make while the view is detached. The Kanzi Android Service host now calls KanziServiceViewAdapterListener.onDetachedFromWindow when a KanziServiceTextureView detaches from its window. (ANDROID-2265)

    See Client view lifecycle and Kanzi 4.1.2 migration guide.

  • Fixed the issue where the Kanzi Android Service stopped rendering and handling input for a client application after a cross-application transition back to it. This happened when the other client application of the transition terminated in the background, for example when Android stopped it to free memory, or when you force-stopped it. When the client application on the screen terminates, the Kanzi Android Service now keeps the content for the other client application of the transition. See Client application termination. (ANDROID-2263)

  • Fixed these Kanzi Android Service issues (ANDROID-2207):

    • A client application showed no content and did not receive input when the Kanzi Android Service host had hidden its preloaded content with KanziServiceRuntime.handleVisibilityChange. The content is now shown when the client application provides its surface.

    • Hiding or showing preloaded content before its prefab had loaded stalled the load.

    • Showing a preloaded client application without a surface made a debug build of the Kanzi Android Service host terminate when another client application lost its window.

    • The Kanzi Android Service host leaked a surface when a client application provided its surface for content that already had one.

    • The Kanzi Android Service host terminated, also in release builds, when a client application or the Kanzi Android Service host changed the visibility of a client that had no content, for example before its client view attached to a window or after it detached. Kanzi Android Service now ignores such a visibility change.

  • Fixed the issue where KanziServiceRuntime.preloadClientPrefab loaded the startup prefab that a client application had registered instead of the preloaded prefab. With an empty prefab URL, the Kanzi Android Service host terminated when the client application provided its surface. preloadClientPrefab now loads the preloaded prefab, and with an empty prefab URL keeps the startup prefab of the client application. (ANDROID-2246)

  • Fixed the issue where the Kanzi Android Service host terminated, and every client application with it, when a client application pushed data to a data source that does not exist, for example with a mistyped data source URL or a kzb file that is not loaded. The host now logs an error and keeps running. (ANDROID-2261)

Kanzi Studio

  • Fixed the issue where a project could not override a system shader. A file in the project Shaders directory at the same path as a system shader now replaces that system shader everywhere. This includes other system shaders and the material types that Kanzi Studio provides. Clone To Project now keeps the path of the system shader, so a clone overrides the system shader. To make a clone that you made with an earlier version of Kanzi Studio override the system shader, move it to the path that the system shader has. (RENDERING-3549)

    This can change which file an existing project uses. A file that the project already has at the path of a system shader now replaces that system shader. An #include <file.glsl> now finds a file in the Shaders directory before a file next to the shader that contains the #include.

    See Cloning a system shader to your project.

Documentation

  • Fixed the issue where Rendering best practices stated that Kanzi does not transform 3D nodes that have the Visible property disabled. Since Kanzi 4.1.0, Kanzi Engine transforms these nodes and their child nodes, so hiding a 3D node does not save the time that Kanzi Engine spends transforming it. To skip transforming the 3D content of a Viewport 2D node, disable the Visible property of the Scene node or of the Viewport 2D node. (FMW-1770)

  • Fixed the issue where the documentation stated that Kanzi Android framework (droidfw) and Kanzi Java API require Java 8. Since Kanzi 4.0.0, they require Java language level 11 or higher. Also fixed the Groovy example in Working with Kanzi Android framework (droidfw) projects that used JavaVersion.VERSION_1_11, which Gradle does not define. (ANDROID-2271)

See also

Kanzi 4.1.2 migration guide

Known issues