Kanzi 3.9.1 migration guide¶

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

Color blending¶

Kanzi 3.9.1 fixes the rendering of 2D node brushes and introduces new blend modes. See Blending and compositing 2D nodes.

The default blend mode of materials changed from Opaque to Alpha: Premultiplied. When you open a project created with an earlier version of Kanzi Studio which contains materials whose blend mode is not set, Kanzi Studio automatically adds to those materials the Blend Mode property and sets it to Opaque.

The color blending improvements introduce these differences in the Kanzi Engine API between Kanzi 3.9.0 and 3.9.1:

Kanzi 3.9.0	Kanzi 3.9.1
`graphics_enums.hpp` `GraphicsBlendMode` enumerator values: `GraphicsBlendModeOpaque` `GraphicsBlendModeAlpha` `GraphicsBlendModeAdditive` `GraphicsBlendModePremultipliedAlpha` `GraphicsBlendModeMixedAlpha`	`graphics_blend_mode.hpp` integer variables: `GraphicsBlendModeAdditive` `GraphicsBlendModeAlpha` `GraphicsBlendModeClear` `GraphicsBlendModeDestinationAtop` `GraphicsBlendModeDestinationIn` `GraphicsBlendModeDestinationOut` `GraphicsBlendModeDestinationOver` `GraphicsBlendModeExclusiveOr` `GraphicsBlendModeMixedAlpha` `GraphicsBlendModeMultiply` `GraphicsBlendModeOpaque` `GraphicsBlendModePremultipliedAlpha` `GraphicsBlendModeScreen` `GraphicsBlendModeSourceAtop` `GraphicsBlendModeSourceIn` `GraphicsBlendModeSourceOut`
	Adds `blendMode` parameter to: `BrushRenderer::updateRender` `BrushRenderer::updateRenderOverride` and its implementations in `ContentBrushRenderer`, `MaterialBrushRenderer`, `TextureBrushRenderer`, and `ColorBrushRenderer` `NodeCompositor2D::updateRender` `NodeVisual2D::storeRenderingParameters`
`GlRenderState::setValue(GraphicsBlendMode value)`	`GlRenderState::setBlendModeValue` `(optional<int> value)`
`BrushRenderer::RenderMode` enumerator values: `RenderModeNone` `RenderModeInvalid` `RenderModeOpaqueNoContent` `RenderModeTranslucentNoContent` `RenderModeOpaque` `RenderModeTranslucent`	`BrushRenderer::RenderMode` enumerator values: `RenderModeNone` `RenderModeContent` `RenderModeNoContent`
`BrushRenderer::updateRender()`, `BrushRenderer::updateRender(bool forceOpaque)`	`BrushRenderer::updateRender(optional<int> blendMode, bool forceOpaque, bool translucencyHint)`
`BrushRenderer::hasOpaqueRenderMode()`	Removed.
`ColorBrushRenderer` and `TextureBrushRenderer` derive from `GlBrushRenderer`	`ColorBrushRenderer` and `TextureBrushRenderer` derive from `ContentBrushRenderer`
`ColorBrushRenderer` and `TextureBrushRenderer` methods: `getRenderOpacityValue` `getBlendModeValue` `getContentTextureValue` `getMaterial`	Methods inherited from the base classes: `ContentBrushRenderer::getRenderOpacityValue` `BrushRenderer::getBlendModeValue` `ContentBrushRenderer::getContentTextureValue` `ContentBrushRenderer::getMaterial`
`ContentBrushRenderer::getBlendModeValue`	Inherited from `BrushRenderer::getBlendModeValue`
`Brush::setOpaque`	`Brush::setContentTranslucent`
`Brush::getContentTexture`	Removed. Use `BrushRenderer::getContentTexture` instead.
`Brush::setContentTexture`	Removed. Use `BrushRenderer::setContentTexture` instead.
`NodeCompositor2D::` `isOpacityCompositionRequest`	`NodeCompositor2D::` `isOpacityAndChildrenCompositionRequest`
In: `NodeVisual2D::setForegroundBrushRenderer` `NodeVisual2D::setBackgroundBrush` Data type of the `brush` parameter is `BrushSharedPtr`.	Data type of the `brush` parameter is `Brush*`.
In: `GlRenderValueBinding::update` `RenderStatePropertyNotificationHandler::update`, `updateOverride` and its implementations Template functions `acquireRenderValueFromPropertyDefault` and `acquireRenderValueFromProperty` and their associated specializations Data type of the `object` parameter is `Object`.	Data type of the `object` parameter is `PropertyObject`.
`RenderEntry3D` constructor is converting.	`RenderEntry3D` constructor is explicit which does not allow implicit type conversions.
	These classes and functions use `KANZI_COREUI_API`: `ColorBrushRenderer` `MaterialBrushRenderer` `TextureBrushRenderer` `acquireUniformLocation` `getUniformElementCount` All specializations of `updateRenderValue` and `updateRenderValueOverride`
	`GlRenderValue` template class uses `KANZI_COREUI_TEMPLATE_API`.

Cubemaps¶

Kanzi 3.9.1 fixes the rendering of cubemap images. You no longer need to flip cubemap images or modify reflections to get the expected result.

To migrate your project to Kanzi 3.9.1, adjust png cubemaps to work with the fix:

When you prepare cubemap images in a third-party tool, do not flip the images along any axes.
Use the same cubemap images that you use to generate a dds cubemap texture.
In a cubemap texture use the PosZ Image property to set the front face (behind the camera) and the NegZ Image property to set the back face (in front of camera) of the cubemap.
Do not modify the reflection vector used for sampling. Use the real-world direction.

If your project contains png cubemaps whose sides you manually flipped in a third-party image editing tool to make those cubemaps work in a previous version of Kanzi Studio, to avoid flipping the sides again, you can instruct Kanzi Studio to not process the images further by naming the png files according to the pattern <TextureName> <direction><Axis>.png:

PosX Image: <TextureName> posX.png
NegX Image: <TextureName> negX.png
PosY Image: <TextureName> posY.png
NegY Image: <TextureName> negY.png
PosZ Image: <TextureName> posZ.png
NegZ Image: <TextureName> negZ.png

Make sure that you include the space character in the filenames.

The side image files in cubemap textures that you imported from dds files already follow this naming convention.

See Using cubemap textures.

Input and focus handling¶

List Box and Scroll View nodes created using the Kanzi Engine API are no longer by default focusable. To enable a List Box or Scroll View node to get keyboard focus, add the Node::FocusableProperty and set it to true.

Kanzi Studio by default adds and enables the Focus > Focusable property in List Box and Scroll View nodes.

Activities and focus¶

Activity Host nodes no longer require the Save Last Focused Node and Focus Scope Type properties to enable the saving and restoring of the last-focused node in Activity nodes. Starting with this version, Kanzi Studio no longer adds these properties by default to Activity Host nodes.

The presence of these properties does not affect the application behavior. However, you can remove the Save Last Focused Node and Focus Scope Type properties from existing Activity Host nodes in your project.

Changes to Code Behind¶

Removed the requirement to set the KANZI_HOME environment variable for Code Behind.

Changes to the Kanzi Activity system¶

Refactored these Kanzi Activity messages, message arguments, and properties:

Kanzi 3.9.0	Kanzi 3.9.1
`ActivityConcept::PrefabAttachedMessage`	`ActivityHostConcept::ActivityPrefabAttachedMessage`
`ActivityConcept::PrefabDetachedMessage`	`ActivityHostConcept::ActivityPrefabDetachedMessage`
`ActivityConcept::StatusChangedMessageArguments::StatusArgument`	`ActivityConcept::StatusChangedMessageArguments::ActivityStatus`
`DataDrivenExclusiveActivityHostConcept::ActiveItemIndexProperty`	`DataDrivenExclusiveActivityHostConcept::ActiveActivityIndexProperty`

When you open a Kanzi Studio project that uses these messages, Kanzi Studio automatically applies the change.

Renamed these Kanzi Activity APIs and variables:

Kanzi 3.9.0	Kanzi 3.9.1
`DataDrivenExclusiveActivityHostConcept::setActivityTemplate(string prefabUrl)`	`DataDrivenExclusiveActivityHostConcept::setActivityTemplate(string_view prefabUrl)`
`DataDrivenExclusiveActivityHostConcept::s_defaultActiveItemIndex`	`DataDrivenExclusiveActivityHostConcept::s_defaultActiveActivityIndex`
`DataDrivenExclusiveActivityHostConcept::getActiveItemIndex()`	`DataDrivenExclusiveActivityHostConcept::getActiveActivityIndex()`
`DataDrivenExclusiveActivityHostConcept::setActiveItemIndex()`	`DataDrivenExclusiveActivityHostConcept::setActiveActivityIndex()`

Changes to the Kanzi Java API¶

Enum classes¶

All Kanzi Java API enum classes now implement the interface Enum and as such provide methods:

getValue() to get integer value of an enumerator
toEnum() to convert from an integer value to respective enumerator

In Kanzi 3.9.0 some enum classes exposed these functionalities through differently named methods, which are renamed in Kanzi 3.9.1.

Kanzi 3.9.0	Kanzi 3.9.1
`swigValue()`	`getValue()`
`swigToEnum()`	`toEnum()`

Renamed PropertyType.DataType to PropertyDataType. The names of the property data types now match those of the native Kanzi Engine API.

Kanzi 3.9.0	Kanzi 3.9.1
`PropertyType.DataType.Bool`	`PropertyDataType.PropertyDataTypeBool`
`PropertyType.DataType.Color`	`PropertyDataType.PropertyDataTypeColor`
`PropertyType.DataType.Float`	`PropertyDataType.PropertyDataTypeFloat`
`PropertyType.DataType.Int`	`PropertyDataType.PropertyDataTypeInt`
`PropertyType.DataType.Matrix3x3`	`PropertyDataType.PropertyDataTypeMatrix3x3`
`PropertyType.DataType.Matrix4x4`	`PropertyDataType.PropertyDataTypeMatrix4x4`
`PropertyType.DataType.Resource`	`PropertyDataType.PropertyDataTypeResource`
`PropertyType.DataType.SRT2D`	`PropertyDataType.PropertyDataTypeSRT2D`
`PropertyType.DataType.SRT3D`	`PropertyDataType.PropertyDataTypeSRT3D`
`PropertyType.DataType.String`	`PropertyDataType.PropertyDataTypeString`
`PropertyType.DataType.Vector2`	`PropertyDataType.PropertyDataTypeVector2`
`PropertyType.DataType.Vector3`	`PropertyDataType.PropertyDataTypeVector3`
`PropertyType.DataType.Vector4`	`PropertyDataType.PropertyDataTypeVector4`

Resource Manager¶

Kanzi 3.9.1 changes the custom resource manager protocol handler interface:

The ResourceManager.LoadTask interface is now an abstract class.
ResourceManager is no longer an argument to the loadFunction and finishFunction. Use ResourceManager.LoadTask.getResourceManager() instead.

Kanzi 3.9.0	Kanzi 3.9.1
class MyLoadTask implements ResourceManager.LoadTask { @Override public void loadFunction( ResourceManager resourceManager) { ... } @Override public void finishFunction( ResourceManager resourceManager) { ... } @Override public Resource getResult() { ... } }	class MyLoadTask extends ResourceManager.LoadTask { @Override public void loadFunction() { ... } @Override public void finishFunction() { ... } @Override public Resource getResult() { ... } }

Kanzi 3.9.0

Kanzi 3.9.1

class MyLoadTask
    implements ResourceManager.LoadTask
{
    @Override
    public void loadFunction(
        ResourceManager resourceManager)
    {
        ...
    }

    @Override
    public void finishFunction(
        ResourceManager resourceManager)
    {
        ...
    }

    @Override
    public Resource getResult()
    {
        ...
    }
}

class MyLoadTask
    extends ResourceManager.LoadTask
{
    @Override
    public void loadFunction()
    {
        ...
    }

    @Override
    public void finishFunction()
    {
        ...
    }

    @Override
    public Resource getResult()
    {
        ...
    }
}