Kanzi 3.9.7 migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.9.6 to Kanzi 3.9.7.

Changes related to multisampling

Changed the data type of these properties, which set the number of multisample anti-aliasing samples, from integer to enumeration:

• CompositionTargetRenderPass::MultisampleLevelProperty

• ProgressiveRenderingViewport2D::MultisampleLevelProperty

The available values now consist of valid sample counts. In previous versions of Kanzi, it was possible to set a non-valid sample count, which the driver rounded up to a valid value. The enumeration values correspond to the sample counts, so you can cast them, if needed.

Changes in the NodeCompositor2D and NodeEffect2D classes

Introduced the CompositionContentRequirements struct that contains the parameters for setting the requirements for composition and effect render targets:

struct CompositionContentRequirements
{
   /// Required size of the source content to be used by the effect.
   Vector2 size;
   /// Whether the content requires alpha channel.
   bool alpha;
   /// Whether the content requires depth buffer.
   bool depth;
   /// Whether the content requires stencil buffer.
   bool stencil;
   /// MSAA sample count for content buffer.
   unsigned int numSamples;
};

Changes in the NodeCompositor2D class:

Kanzi 3.9.6	Kanzi 3.9.7
bool beginComposition(Renderer3D& renderer, CompositionStack& compositionStack, CompositionManager* compositionManager, Vector2 requiredSize, bool alphaRequired, bool depthRequired, bool stencilRequired, bool drawFlagSet);	bool beginComposition(Renderer3D& renderer, CompositionStack& compositionStack, CompositionManager* compositionManager, const CompositionContentRequirements& requirements, bool drawFlagSet); See NodeCompositor2D::beginComposition.
TextureSharedPtr beginFinalComposition(CompositionStack& compositionStack, CompositionManager* compositionManager, Vector2 requiredSize, bool alphaRequired, bool depthRequired, bool stencilRequired, bool needsRender);	TextureSharedPtr beginFinalComposition(CompositionStack& compositionStack, CompositionManager* compositionManager, const CompositionContentRequirements& requirements, bool needsRender); See NodeCompositor2D::beginFinalComposition.
void updateRender(Node2D& node, Vector2 actualSize, bool alphaRequired, bool depthRequired, bool stencilRequired, optional<int> blendMode, float opacity, bool translucencyHint);	void updateRender(Node2D& node, const CompositionContentRequirements& requirements, optional<int> blendMode, float opacity, bool translucencyHint); See NodeCompositor2D::updateRender.
bool updatePersistentCompositionTarget(Node2D& node, TextureSharedPtr& managedCompositionTarget, Vector2 requiredSize, bool alphaRequired, bool depthRequired, bool stencilRequired);	bool updatePersistentCompositionTarget(Node2D& node, TextureSharedPtr& managedCompositionTarget, const CompositionContentRequirements& requirements); See NodeCompositor2D::updatePersistentCompositionTarget.

Changes in the NodeEffectRenderer2D class:

Kanzi 3.9.6	Kanzi 3.9.7
void beginEffect(Renderer3D &renderer, CompositionStack& compositionStack, CompositionManager* compositionManager, const Matrix3x3& worldTransform, Vector2 requiredSize, bool alphaRequired, bool depthRequired,  bool stencilRequired);	void beginEffect(Renderer3D& renderer, CompositionStack& compositionStack, CompositionManager* compositionManager, const Matrix3x3& worldTransform, const CompositionContentRequirements& requirements); See NodeEffectRenderer2D::beginEffect.
void beginEffectOverride(Renderer3D &renderer, CompositionStack& compositionStack, CompositionManager* compositionManager, const Matrix3x3& worldTransform, Vector2 requiredSize, bool alphaRequired, bool depthRequired,  bool stencilRequired);	void beginEffectOverride(Renderer3D& renderer, CompositionStack& compositionStack, CompositionManager* compositionManager, const Matrix3x3& worldTransform, const CompositionContentRequirements& requirements); See NodeEffectRenderer2D::beginEffectOverride.
void beginInitialEffectPass(Renderer3D &renderer, CompositionStack& compositionStack, CompositionManager* compositionManager, bool alphaRequired, bool depthRequired, bool stencilRequired);	void beginInitialEffectPass(Renderer3D& renderer, CompositionStack& compositionStack, CompositionManager* compositionManager, const CompositionContentRequirements& requirements); See NodeEffectRenderer2D::beginInitialEffectPass.

Changes to Kanzi Java API

CallbackBindingProcessor

Kanzi Java API BindingProcessor now inherits KanziObject instead of NativeObject. This means that Kanzi Java API CallbackBindingProcessor.create now returns ObjectRef<CallbackBindingProcessor> instead of CallbackBindingProcessor.

Support for enum properties

Kanzi Java API now supports properties with enum data types:

• In setter and getter functions, you can now use enum values instead of integers.

  For example, you can replace

  textNode.setProperty(TextBlock2D.FontHintingPreferenceProperty, 1); // FontHintingPreference::NativeHinting
  

  with

  textNode.setProperty(TextBlock2D.FontHintingPreferenceProperty, FontHintingPreference.NativeHinting);
  

• In KanziObject.getProperty, you no longer have to provide the class of an enum property as a second parameter.

  For example, you can replace

  Node.HorizontalAlignment value = node.getProperty(Node.HorizontalAlignmentProperty, Node.HorizontalAlignment.class);
  

  with

  Node.HorizontalAlignment value = node.getProperty(Node.HorizontalAlignmentProperty);
  

• Because of differences between Java and Kotlin in how interface inheritance works, access of built-in enums works differently.

  For example, with the metadata.NodeMetadata.HorizontalAlignmentProperty property:

  • This works in both Java and Kotlin:

    NodeEnums.HorizontalAlignment.Center;
    

  • This works only in Java:

    Node.HorizontalAlignment.Center;
    

Removed these unused enums:

• Node3D.RenderMode

• Node2D.RenderType

Changes to setting and removing of bindings

The return type of these functions changed from AbstractBindingRuntimeSharedPtr to BindingRuntimeHandle:

• BindingHostConcept::removeBinding

• BindingHostConceptImpl::setBinding

• BindingHostConceptImpl::setModifierBinding

• BindingHostConceptImpl::setBindingWithOwner

• BindingHostConceptImpl::setModifierBindingWithOwner

The BindingRuntimeHandle -> operator returns a link to AbstractBindingRuntime. This way the binding runtime functions work identically.

Changes to Graphics Output and Desktop

In Kanzi 3.9.7, you can set on the platforms that use the GBM windowing system which graphics card you want your Kanzi application to use. The improvement introduced:

• In the makeLegacyGraphicsOutput function and LegacyGraphicsOutput::LegacyGraphicsOutput constructor, the desktopProperties parameter.

• In the kzs_desktop.h::kzsDesktopCreate and kzs_desktop.h::kzsDesktopNativeCreate functions, the desktopPropertiesRequested parameter.

Kanzi 3.9.6	Kanzi 3.9.7
KANZI_COREUI_API GraphicsOutputSharedPtr makeLegacyGraphicsOutput(const struct KzsSurfaceProperties* surfaceProperties, const NativeWindowProperties* windowProperties);	KANZI_COREUI_API GraphicsOutputSharedPtr makeLegacyGraphicsOutput(const struct KzsSurfaceProperties* surfaceProperties, const NativeWindowProperties* windowProperties, const NativeDesktopProperties* desktopProperties); See makeLegacyGraphicsOutput.
explicit LegacyGraphicsOutput(const struct KzsSurfaceProperties* surfaceProperties, const NativeWindowProperties* windowProperties);	explicit LegacyGraphicsOutput(const struct KzsSurfaceProperties* surfaceProperties, const NativeWindowProperties* windowProperties, const NativeDesktopProperties* desktopProperties); See LegacyGraphicsOutput::LegacyGraphicsOutput.
KANZI_COREUI_API kzsError kzsDesktopCreate(struct KzsDesktop** out_desktop);	KANZI_COREUI_API kzsError kzsDesktopCreate(const kanzi::NativeDesktopProperties* desktopPropertiesRequested, struct KzsDesktop** out_desktop); See kzs_desktop.h::kzsDesktopCreate.
KANZI_COREUI_API kzsError kzsDesktopNativeCreate(struct KzsDesktopNative** out_desktopNative);	KANZI_COREUI_API kzsError kzsDesktopNativeCreate(const kanzi::NativeDesktopProperties* desktopPropertiesRequested, struct KzsDesktopNative** out_desktopNative); See kzs_desktop.h::kzsDesktopNativeCreate.

Changes to Java Code Behind

If your Kanzi application is based on one of the Android templates and you want to add Java Code Behind to the Kanzi Studio project of that application, migrate your application.

To migrate your Kanzi application:

1. In Android Studio, open the Android application of your Kanzi application. In the main menu select File > Project Structure. In the Project Structure window, select the Project tab, and set:

   • Android Gradle Plugin Version to 7.2.2

   • Gradle Version to 7.3.3

   Click OK.

   

2. In app/src/main/AndroidManifest.xml, from the manifest element remove the package attribute.

   For example, change

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
         package="com.example.myapplication">
   

   to

   <manifest xmlns:android="http://schemas.android.com/apk/res/android">
   

3. In app/build.gradle, add to the android scope the namespace property.

   The new tooling requires the compileSdk and targetSdk properties to be set to Android API level 31 or higher.

   android {
       namespace 'com.example.myapplication'
       compileSdk 31
   
       defaultConfig {
           applicationId "com.example.myapplication"
           minSdk 26
           targetSdk 31
   

If your application already has a plugin as a source project or Java Code Behind, repeat the procedure for their AndroidManifest.xml and build.gradle files.

Changes to brush renderers

Kanzi 3.9.7 simplifies brush renderers to be more uniform. The improvement introduced these changes:

• Removed the GlBrushRenderer base class and moved most of the functionality from different brush classes to the BrushRenderer base class.

• Removed the RenderValuePropertyNotificationHandler class.

  Because all brushes now use GlRenderState to store the render values, RenderValuePropertyNotificationHandler members are not needed. Kanzi now maps properties to uniforms automatically in the render state.

If you used a previous version of Kanzi to implement your own derived brush class with an associated brush renderer class, use these instructions to migrate your application to Kanzi 3.9.7:

• Instead of inheriting GlBrushRenderer, inherit BrushRenderer.

• The functionality of these functions is now provided by the base class:

  • getRenderOpacityValue()

  • getContentTextureValue()

  • getBlendModeValueOverride()

  • setBlendModeOverride()

  • setBlendModeFallback()

  If you implemented any of these functions, in most cases you can just remove the implementations.

• If you implemented the bindOverride() function, modify it to use the form void bindOverride(Renderer3D&, PropertyObject*). See BrushRenderer::bindOverride.

  The property object is an additional object from which to fetch fallback values for properties. For MaterialBrush, this is the material, which lets you react to property changes in the material. For all other brushes that use immutable materials, set this parameter to nullptr.

• The BrushRenderer::isChangeCounterSame and BrushRenderer::updateChangeCounter functions are now virtual.

  If your brush uses mutable materials, to react to changes in the material properties, the brush must track the material change counter in these functions. If your brush uses immutable materials, do not implement these functions.

Changes to the PropertyObject API

To improve the Kanzi Engine code quality, changed the PropertyObject API. Deprecated PropertyObject::validatePropertyModifiers. Use PropertyObject::validatePropertyModifiersAndNotifyHandlers instead.

Changes to the bindings API

From binding_processor_runtime.hpp removed the m_lookupContext class member.

If your Kanzi application implements a custom binding processor runtime, replace the use of m_lookupContext with getBindingRuntime().getLookupContext().

See also

Kanzi 3.9.7 release notes

Known issues