Kanzi 3.9.9 migration guide¶

Use this migration guide to update Kanzi applications from Kanzi 3.9.8 to Kanzi 3.9.9.

Changes to Kanzi Java API¶

Most of the create functions now return the ObjectRef of the corresponding class instead of the base class. You can use both the base and derived functionality directly from the returned value, without the need for class cast.

For example:

	Kanzi 3.9.8	Kanzi 3.9.9
Return type	`<T extends Resource> ObjectRef<T> ColorBrush.create(Domain domain)`	`ObjectRef<ColorBrush> ColorBrush.create(Domain domain)`
Usage	`ObjectRef<Resource> myBrush = ColorBrush.create(domain, "myBrush")`	`ObjectRef<ColorBrush> myBrush = ColorBrush.create(domain, "myBrush")`

To conform to the Java convention for indices, all method parameters and returns that represent indices now use int.

For example:

Kanzi 3.9.8

Kanzi 3.9.9

public float Vector2.get(long index)

public float Vector2.get(int index)

public Vector3 getRow(long index)

public Vector3 getRow(int index)
Removed the BitmapFont.create function. The function did not work as intended, because the BitmapFont class has no public constructors.

Kanzi 3.9.8	Kanzi 3.9.9
`public float Vector2.get(long index)`	`public float Vector2.get(int index)`
`public Vector3 getRow(long index)`	`public Vector3 getRow(int index)`

Changes to brush rendering¶

In previous versions of Kanzi, in some cases, setting brush properties in a 2D node did not work. Kanzi determined the need to render a brush during the layouting phase, which caused only the property value set in the brush to affect the rendering result.

Kanzi 3.9.9 decides the brush rendering in the rendering phase and takes into account all sources of property values.

The improvement introduces these changes to the brush rendering APIs:

Added these functions:
In the BrushRenderer::bindOverride function, changed the type of the return value to Boolean.
Renamed the NodeVisual2D::storeRenderingParameters function to NodeVisual2D::updateRender and removed the translucencyHint parameter.
Renamed the NodeVisual2D::updateBrushRenderers function to NodeVisual2D::updateBlendSettings.
Made these functions const:
Removed:
- From the Brush class:
  - The TranslucencyBits enumerator
  - The getBlendMode, isOpaque, isTranslucent, setContentTranslucent, and setRenderable functions
- From the classes that inherit Brush, the initialize and calculateRenderingProperties functions
- BrushRenderer::hasRenderMode
- ColorBrushRenderer::updateRenderMode, TextureBrushRenderer::updateRenderMode
- GlRenderValueBinding::setBlendModeFallback
- Node2D::isForegroundTranslucencyRequested
- From the BrushRenderer::updateRender function, the blendMode and translucencyHint parameters.
- From the BrushRenderer::updateRenderOverride function, the blendMode and translucencyHint parameters.
- From the NodeCompositor2D::updateRender function, the translucencyHint parameter.

Changes to shader processing¶

In the previous versions of Kanzi, when Kanzi Studio failed to parse a shader, Kanzi wrote the shader code to the kzb file without preprocessing. Kanzi 3.9.9 replaces such shaders with an error shader that renders solid red.

You can use the Kanzi Engine C++ API to create and use shaders that are not supported by Kanzi Studio. See ShaderProgram.

Changes to morph weights¶

In the previous versions of Kanzi, when you set a morph mesh for a Model3D node, Kanzi Engine overwrote the morph weights with the default weights from the Morph. Kanzi 3.9.9 preserves the morph weights.

To replicate the old behavior, set the Model3D::MeshProperty to nullptr, and assign the new Morph.

Changes in Boolean to string conversions¶

In previous versions of Kanzi, conversions from Boolean to string did not always result in the same value. For example:

Set Property action, which set the value of a string property based on the value of a Boolean property, resulted in “1” or “0”.
Any Boolean-to-string property binding in the Kanzi Engine C++ API resulted in “1” or “0”.
In a binding expression, an implicit cast of a literal Boolean value to string resulted in “True” or “False”, but casting with string resulted in “true” or “false”.

In Kanzi 3.9.9, all conversions from Boolean to string result in lower case “true” or “false”.

To migrate your Kanzi application from an earlier version, make sure that all string values that you compare against Boolean values are lower case “true” or “false”.

For example, in a state manager whose string controller property gets its value from a Boolean property using a Set Property action, change the states to use values “true” and “false” instead of “1” and “0”.