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()
    {
        ...
    }
}

See also

Kanzi 3.9.1 release notes

Known issues