Kanzi 4 beta migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.9 to Kanzi 4.0.

Note

Depending on your projects reliance on changes mentioned herein, it may require less effort to assemble a new project on Kanzi 4.0.0 than migrating.

Upgrade to Visual Studio 2022

Kanzi no longer supports Kanzi Engine libraries for Visual Studio 2017 and 2019.

For Kanzi Studio projects with a Kanzi Engine plugin, rebuild the plugin with Visual Studio 2022 and import the plugin DLL to the Kanzi Studio project.

Introduction of Kanzi Graphics

Introduction of Kanzi Graphics changes how Kanzi applications interact with the Kanzi rendering subsystem.

Most functions in the Renderer class were removed. Use the Kanzi Graphics API with the configured backend (Open GL, Open GL ES, or Vulkan) instead.

Kanzi Graphics consists of these major parts:

  • Create objects with the gfx::create function and the GraphicsCreateInfo structs.

  • Kanzi records GraphicsCommands into a command buffer, and Kanzi Graphics backend processes these commands for a specific graphics API.

  • For Kanzi Studio projects with a Kanzi Engine plugin, the plugin DLL needs to be re-imported to the Kanzi Studio project.

  1. Rebuild the plugin using Kanzi 4.0.0 beta2.

  2. In the Library > Kanzi Engine Plugins, delete the Kanzi Engine plugin and import the updated Kanzi Engine plugin.

  • Removed these classes, members, or functions:

    • kanzi::acquireUniformLocation

    • kanzi::getUniformElementCount

    • kanzi::GLBufferHandle

    • kanzi::GLFramebufferHandle

    • kanzi::GlGraphicsLogScope

    • kanzi::GlGraphicsAdapter

    • kanzi::GlGraphicsAdapterCallGles

    • kanzi::GlGraphicsAdapterCallOpenGl

    • kanzi::GlGraphicsAdapterCheckForErrors

    • kanzi::GlGraphicsAdapterLogger

    • kanzi::GLGraphicsOutput

    • kanzi::GLProgramHandle

    • kanzi::GLRenderbufferHandle

    • kanzi::GlRenderState::acquireUniformLocation

    • kanzi::GlRenderState::allocateValues

    • kanzi::GlRenderState::RenderValueUnion

    • kanzi::GlRenderState::RenderValueInfo

    • kanzi::GlRenderState::TextureRenderValue

    • kanzi::GlRenderValueBase

    • kanzi::GLShaderHandle

    • kanzi::GLTextureHandle

    • kanzi::GlTextureRenderValue

    • kanzi::Mesh::bind

    • kanzi::Mesh::bindAttribute

    • kanzi::Mesh::bindAttributes

    • kanzi::Mesh::bindIndicies

    • kanzi::Renderer::getActiveGraphicsContext

    • kanzi::Renderer::getActiveSurfaceVendor

    • kanzi::Renderer::getUniformLocationSlow

    • kanzi::Renderer::getUniformArrayLength

    • kanzi::Renderer::setUniformIntArray

    • kanzi::Renderer::setUniformFloatArray

    • kanzi::Renderer::setUniformVecArray

    • kanzi::Renderer::setUniformColorArray

    • kanzi::Renderer::setUniformMatArray

    • kanzi::Renderer::setUniformInteger

    • kanzi::Renderer::setUniformFloat

    • kanzi::Renderer::setUniformVec2

    • kanzi::Renderer::setUniformVec3

    • kanzi::Renderer::setUniformVec4

    • kanzi::Renderer::setUniformColorRGBA

    • kanzi::Renderer::setUniformMatrix3x3

    • kanzi::Renderer::setUniformMatrix4x4

    • kanzi::Renderer::setActiveScalar

    • kanzi::Renderer::getActiveScalar

    • kanzi::Renderer::calculateProjectionCameraWorldMatrix

    • kanzi::Renderer::applyFixedUniformTime

    • kanzi::Renderer::applyFixedUniformWindowSize

    • kanzi::Renderer::applyTransformationUniform

    • kanzi::Renderer::applyTransformation

    • kanzi::Renderer::applyTextureSizeUniforms

    • kanzi::Renderer::applyTexture

    • kanzi::Renderer::detachTexture

    • kanzi::Renderer::setUniformTexture

    • kanzi::Renderer::generateTexture

    • kanzi::Renderer::deleteTexture

    • kanzi::Renderer::setTextureAddressingMode

    • kanzi::Renderer::setTextureSwizzleMask

    • kanzi::Renderer::setTextureSwizzleEachChannel

    • kanzi::Renderer::deleteShaderProgram

    • kanzi::Renderer::deleteShader

    • kanzi::Renderer::generateFramebuffer

    • kanzi::Renderer::deleteFramebuffer

    • kanzi::Renderer::invalidateFramebufferAttachments

    • kanzi::Renderer::framebufferRenderbuffer

    • kanzi::Renderer::generateRenderbuffer

    • kanzi::Renderer::deleteRenderbuffer

    • kanzi::Renderer::bindRenderbuffer

    • kanzi::Renderer::renderbufferStorage

    • kanzi::Renderer::generateBuffer

    • kanzi::Renderer::setVertexBufferData

    • kanzi::Renderer::setIndexBufferData

    • kanzi::Renderer::setVertexBufferSubData

    • kanzi::Renderer::setIndexBufferSubData

    • kanzi::Renderer::deleteBuffer

    • kanzi::Renderer::BufferAccessMode

    • kanzi::Renderer::mapVertexBuffer

    • kanzi::Renderer::unmapVertexBuffer

    • kanzi::Renderer::mapIndexBuffer

    • kanzi::Renderer::unmapIndexBuffer

    • kanzi::Renderer::enableVertexAttributeArray

    • kanzi::Renderer::disableVertexAttributeArray

    • kanzi::Renderer::getActiveShaderHandle

    • kanzi::Renderer::getActiveShaderAttributeMap

    • kanzi::Renderer::beginMaterialSetup

    • kanzi::Renderer::endMaterialSetup

    • kanzi::Renderer::pushStatistics

    • kanzi::Renderer::popStatistics

    • kanzi::Renderer::getIndexCount

    • kanzi::Renderer::getTriangleCount

    • kanzi::Renderer::getVertexCount

    • kanzi::Renderer::getInstanceCount

    • kanzi::Renderer::getBatchCount

    • kanzi::Renderer::getShaderSwitchCount

    • kanzi::Renderer::getUniformSendCount

    • kanzi::Renderer::getTextureSwitchCount

    • kanzi::Renderer::getFramebufferSwitchCount

    • kanzi::Renderer::getBufferSwitchCount

    • kanzi::Renderer::getHeavyweightCallCount

    • kanzi::Renderer::getHalfFloatVertexAttributeSupport

    • kanzi::Renderer::getTexStorageSupport

    • kanzi::Renderer::getGLFormatTriplet

    • kanzi::Renderer::clearUniformCaches

    • kanzi::Renderer::TextureUnitInfo

    • kanzi::Renderer::RenderingChangeStateFlag

    • kanzi::Renderer::refreshRenderContext

    • kanzi::Renderer::enableState

    • kanzi::Renderer::disableState

    • kanzi::Renderer::setState

    • kanzi::Renderer::getState

    • kanzi::Renderer::setBlendMode

    • kanzi::Renderer::getBlendMode

    • kanzi::Renderer::setCullMode

    • kanzi::Renderer::getCullMode

    • kanzi::Renderer::setDepthTest

    • kanzi::Renderer::getDepthTest

    • kanzi::Renderer::setLineWidth

    • kanzi::Renderer::getLineWidth

    • kanzi::Renderer::clear

    • kanzi::Renderer::resetClearTarget

    • kanzi::Renderer::addClearTarget

    • kanzi::Renderer::getClearMode

    • kanzi::Renderer::addClearColor

    • kanzi::Renderer::removeClearTarget

    • kanzi::Renderer::isClearEnabled

    • kanzi::Renderer::setClearColor

    • kanzi::Renderer::setClearDepthValue

    • kanzi::Renderer::setClearStencil

    • kanzi::Renderer::setColorWriteMode

    • kanzi::Renderer::getColorWriteMode

    • kanzi::Renderer::setViewport

    • kanzi::Renderer::getViewport

    • kanzi::Renderer::setScissorTest

    • kanzi::Renderer::getScissor

    • kanzi::Renderer::setVertexBuffer

    • kanzi::Renderer::setIndexBuffer

    • kanzi::Renderer::drawBuffers

    • kanzi::Renderer::setVertexCount

    • kanzi::Renderer::setIndexCount

    • kanzi::Renderer::setIndexData

    • kanzi::Renderer::setInstanceCount

    • kanzi::Renderer::setActiveTextureUnit

    • kanzi::Renderer::bindTexture

    • kanzi::Renderer::setTextureImage2D

    • kanzi::Renderer::setTextureSubImage2D

    • kanzi::Renderer::textureStorage

    • kanzi::Renderer::generateMipMaps

    • kanzi::Renderer::setTextureFilter

    • kanzi::Renderer::setTextureCompare

    • kanzi::Renderer::setTextureMaximumLevel

    • kanzi::Renderer::createShader

    • kanzi::Renderer::createShaderProgram

    • kanzi::Renderer::attachShaderToProgram

    • kanzi::Renderer::detachShaderFromProgram

    • kanzi::Renderer::bindAttributeToLocation

    • kanzi::Renderer::linkShaderProgram

    • kanzi::Renderer::compileSourceShader

    • kanzi::Renderer::deployBinaryShader

    • kanzi::Renderer::deployBinaryProgram

    • kanzi::Renderer::loadProgramFromCache

    • kanzi::Renderer::saveProgramToCache

    • kanzi::Renderer::getCacheFilePath

    • kanzi::Renderer::updateSettings

    • kanzi::Renderer::getProgramBinary

    • kanzi::Renderer::isFramebufferComplete

    • kanzi::Renderer::framebufferTexture2D

    • kanzi::Renderer::applyVertexAttributeArrays

    • kanzi::Renderer::setVertexBufferPointer

    • kanzi::Renderer::setVertexBufferPointer

    • kanzi::Renderer::setActiveShaderHandle

    • kanzi::Renderer::setActiveFramebuffer

    • kanzi::Renderer::setColorBufferCount

    • kanzi::Renderer::getActiveFramebuffer

    • kanzi::Renderer::beginVertexArray

    • kanzi::Renderer::setVertexArrayData

    • kanzi::Renderer::endVertexArray

    • kanzi::Renderer::getCurrentVertexArrayFlags

    • kanzi::Renderer::getCurrentVertexArrayAttributeData

    • kanzi::Renderer::isShaderBinaryFormatSupported

    • kanzi::Renderer::isProgramBinaryFormatSupported

    • kanzi::Renderer::applyAttributePointer

    • kanzi::Renderer::supportsTexStorage

    • kanzi::Renderer::setHasTessellationShader

    • kanzi::Renderer::setFillMode

    • kanzi::Renderer::readPixels

    • kanzi::Renderer::setPixelStorePack

    • kanzi::Renderer::setPixelStoreUnpack

    • kanzi::Shader::UniformProperty::uniformLocation

    • kanzi::Shader::hasSamplersWithoutProperties

    • kanzi::Shader::getTextureUniformLocation

    • kanzi::Texture::deployImages

    • kzsGlGraphicsContextCreate

    • kzsGlGraphicsContextDestroy

    • kzsGlGraphicsContextSetActive

    • kzsGlGraphicsContextGetAdapter

    • kzsGlGraphicsContextIsKhrDebugSupported

    • kzsGlGraphicsContextGetVendor

    • kzsGlGraphicsContextGetSurfaceClientAPI

    • kzsGlGraphicsContextGetAPI

    • kzsGlIsExtensionSupported

    • kzsGlGraphicsContextSetLogging

    • kzsGlGraphicsContextGetLogging

    • kzsGlGraphicsContextGetDumpStateOnDrawCalls

    • kzsGlGraphicsContextSetErrorChecking

    • kzsGlGraphicsContextSetDebugCallback

    • kzsGlGraphicsContextGetGlesSymbols

    • kzsGlGraphicsContextGetOpenGlSymbols

  • Removed these functions that have direct replacements:

    Removed

    Use instead

    kanzi::captureCurrentFramebufferToImage

    captureFramebuffer

    kanzi::captureScreenToImage

    captureFramebuffer

    kanzi::GPUBuffer::getNativeHandle

    GPUBuffer::getHandle

    kanzi::Mesh::getNativeVertexBufferHandle

    Mesh::getVertexBufferHandle

    kanzi::Mesh::getNativeIndexBufferHandle

    Mesh::getIndexBufferHandle

    kanzi::Mesh::getNativeInstanceBufferHandle

    Mesh::getInstanceBufferHandle

    kanzi::Renderbuffer::getNativeHandle

    Renderbuffer::getHandle

    kanzi::Renderer::applyFixedUniforms

    GlRenderState::updateFixedFunctionUniforms

    kanzi::Renderer::getMaximumVertexAttributeCount

    gfx::getDeviceProperty (gfx::DevicePropertyId::MaxVertexAttributes)

    kanzi::Renderer::setActiveGLGraphicsOutput

    Renderer::setActiveGraphicsOutput

  • Removed the kanzi::Geometry::drawTextured and kanzi::Geometry::drawUntextured functions. If you use these functions, you can change code like this

    if (isTextured())
{
    geometry.drawTextured(renderer, transform, GraphicsPrimitiveTypeTriangleStrip, material);
}
else
{
    geometry.drawUntextured(renderer, transform, GraphicsPrimitiveTypeTriangleStrip, material);
}

    to

    renderer.setMatrix(FixedMatrixWorld, transform);
renderState.updateTransformationUniforms(renderer);

renderState.draw(renderer, geometry);

Changes to the Renderer API

  • Removed the Renderer3D class. Kanzi used the Renderer3D class to store temporary properties during 3D rendering and provided debug functionality for the Preview.

    This version of Kanzi moves:

    In your application code, change all uses of Renderer3D to use Renderer. This includes all virtual functions that have Renderer3D passed as a parameter.

    Moved these functions from the Renderer3D class to the Renderer class:

    Removed these functions because of refactoring related to the removal of the Renderer3D class. Most of the removed functions are related to debug rendering:

    • Renderer::bindFramebuffer

    • Renderer::setActiveFramebufferCallback

    • Renderer::setDefaultFramebuffer

    • Renderer3D::addVertexAndNormalToFloatArrays

    • Renderer3D::addVertexToFloatArray

    • Renderer3D::applyBoolProperty

    • Renderer3D::applyColorMaterial

    • Renderer3D::applyColorProperty

    • Renderer3D::applyFloatProperty

    • Renderer3D::applyIntProperty

    • Renderer3D::applyMaterial

    • Renderer3D::applyMaterialStrict

    • Renderer3D::applyMatrix3x3Property

    • Renderer3D::applyMatrix4x4Property

    • Renderer3D::applyPropertyType

    • Renderer3D::applySRT2DProperty

    • Renderer3D::applySRT3DProperty

    • Renderer3D::applyStencilSettings

    • Renderer3D::applyTextureProperty

    • Renderer3D::applyVector2Property

    • Renderer3D::applyVector3Property

    • Renderer3D::applyVector4Property

    • Renderer3D::calculateNormal

    • Renderer3D::drawBoxSolidNormal

    • Renderer3D::drawLayerOutlineQuad

    • Renderer3D::drawLayerQuad

    • Renderer3D::drawLayerQuadWithMaterial

    • Renderer3D::drawLineList

    • Renderer3D::drawPrimitives

    • Renderer3D::drawOrientedBoundingBoxSolidNormal

    • Renderer3D::drawPrimitiveBufferTextured

    • Renderer3D::drawPrimitiveBufferUntextured

    • Renderer3D::drawPrimitivesNormal

    • Renderer3D::drawSelectionIndicator

    • Renderer3D::drawQuad

    • Renderer3D::drawTrajectory

    • Renderer3D::drawUntexturedLayerQuad

    • Renderer3D::drawViewportQuadWithTextureSpan

    • Renderer3D::getActiveGLGraphicsOutput

    • Renderer3D::getClearColorOverride

    • Renderer3D::getFloatBuffer

    • Renderer3D::getResourceManager

    • Renderer3D::isBoundingBoxVisualizationEnabled

    • Renderer3D::isColorWriteDisabled

    • Renderer3D::isSkeletonVisualizationEnabled

    • Renderer3D::printInfo

    • Renderer3D::removeClearColorOverride

    • Renderer3D::setActiveGLGraphicsOutput

    • Renderer3D::setBoundingBoxVisualizationEnabled

    • Renderer3D::setClearColorOverride

    • Renderer3D::setDefaultOrthoProjection

    • Renderer3D::setDisableColorWrite

    • Renderer3D::setFramebufferCallback

    • Renderer3D::setLogging

    • Renderer3D::setSkeletonVisualizationEnabled

    • Surface::attach

    • Surface::attachOverride

    Instead, use the DebugVisualization and DebugVisualizationStorage classes to draw and store debug visualizations for nodes.

    The standard DebugRenderRegistry::DebugObjectRenderingFunction automatically used by DebugComposer changed to:

    void (*DebugObjectRenderingFunction)(Renderer& renderer, DebugRenderStorage& storage, DebugVisualization* visualization, NodeSharedPtr object);

    You can access storage to create a debug visualization structure for the Node. If you have done this on a previous frame, the visualization parameter is non-null and you can use it. Geometry stored in the DebugVisualization remains until you remove the Node from the scene graph.

  • Removed the Surface::Usage enumeration.

  • Removed the RenderTargetMode enumeration and modified Texture::CreateInfo and Texture to remove GraphicsFormatFeature and RenderTargetMode settings. The texture create info now uses a mask of gfx::ImageUsageFlag to specify texture usage intent.

  • Removed the GlRenderValue and GlBlendModeRenderValue classes, and updateRenderValue functions, use GlRenderState instead.

  • Removed the GraphicsPrimitiveTypeLineLoop option from the GraphicsPrimitiveType enumeration. Use GraphicsPrimitiveType::GraphicsPrimitiveTypeLineStrip instead, with the first vertex duplicated at the end of the vertex list.

  • Renamed the GlRenderValueBinding class to RenderValueBinding.

  • Removed the GPUBufferType enumeration. Use gfx::BufferUsageFlag instead. When creating a new GPU buffer, use either gfx::BufferUsageFlag::VertexBuffer or gfx::BufferUsageFlag::IndexBuffer.

  • The type of the nativeHandle parameter changed to gfx::NativeTextureHandle in the Texture::create, the overloaded method which was used to create texture from a pre-existing image object.

  • Removed functions left unused, because of the new graphics backend:

    • Renderer::getColorReadFormat

    • Renderer::getColorReadType

Changes to Data-Driven Exclusive Activity Host

Data-Driven Exclusive Activity Host now supports only Activities created from a data source and no longer supports manually added Activities. Use an Exclusive Activity Host instead.

Changes to List Box

Changes to the List Box nodes

In the Grid List Box nodes, the default directional navigation keys no longer move the item selection. In a List Box node, the default directional navigation keys now move the key focus between the focusable list items.

For example, to scroll a Grid List Box with the ↑ and ↓ keys, make the list items focusable. See Handling the key focus in a List Box node.

Changes to the ActivityCodeBehind class

  • In the Kanzi C++ API, in the ActivityCodeBehind class, replaced the onActive, onInactive, onActivating, and onDeactivating callbacks with ActivityCodeBehind::onStatusChange.

    To migrate your Kanzi application, move the content of the onActive, onInactive, onActivating, and onDeactivating callbacks to the ActivityCodeBehind::onStatusChange callback. For example, if you derive from ActivityCodeBehind, change

    void onActive() override
{
   kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Activity status changed: Active"));
}

    to

    void onStatusChange(ActivityConcept::Status status) override
{
   switch(status)
   {
      case ActivityConcept::Status::Active:
         kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Activity status changed: Active"));
         break;
   }
}

  • In both Kanzi C++ (ActivityCodeBehind) and Kanzi Java API (ActivityCodeBehind), removed registerStatusChange, registerStatusChangeOverride, unregisterStatusChange, and unregisterStatusChangeOverride.

    To migrate your Kanzi application, move the content of the registered status change callbacks to the ActivityCodeBehind::onStatusChange callback.

    For example:

    If you derive from ActivityCodeBehind, change

    void registerStatusChangeOverride() override
{
   registerStatusChange(ActivityConcept::Status::Active, [](ActivityConcept::StatusChangedMessageArguments&)
   {
      kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Activity status changed: Active"));
   });
}

    to

    void onStatusChange(ActivityConcept::Status status) override
{
   switch(status)
   {
      case ActivityConcept::Status::Active:
         kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Activity status changed: Active"));
         break;
   }
}

    If you derive from ActivityCodeBehind, change

    @Override
protected void registerStatusChangeOverride()
{
   registerStatusChange(ActivityStatus.Active, (messageArguments) -> {
      Log.info("Activity status changed: Active");
   });
}

    to

    @Override
protected void onStatusChange(ActivityStatus status)
{
   super.onStatusChange(status);
   switch(status)
   {
      case Active:
         Log.info("Activity status changed: Active");
         break;
   }
}

Changes to the ActivityElementImpl and ActivityHostConceptImpl classes

Changes to the File API

In the File class, changed these member functions to use byte instead of char for anonymous data buffer operations:

Function

Signature

File::read

void File::read(byte* buffer, uintmax_t count)

File::tryRead

uintmax_t File::tryRead(byte* buffer, uintmax_t count)

File::write

void write(const byte* buffer, uintmax_t count)

This change applies also to the functions in the ReadOnlyDiskFile, ReadOnlyMemoryFile, and WriteOnlyDiskFile classes, which inherit the File class.

Changes to the Pinch Manipulator

In the PinchManipulator class:

  • Removed these member functions and variables that had no effect:

    • Functions:

      • setRotationRecognitionThreshold

      • setScaleRecognitionThreshold

    • Variables:

      • m_rotateThreshold

      • m_rotating

      • m_scaleThreshold

      • m_scaling

  • Made these member variables private:

    • m_normalizedReferenceVector

    • m_previousMiddle

    • m_referenceScale

    • m_touchIdA

    • m_touchIdB

Changes to application configuration

  • Removed the enumeration value MultisamplePreference::MultisamplePreferenceImplicit. This also removes the application configuration file option

    MultisamplePreference = "implicit"

    This reflects a broader change, that removes the support for implicit multisampling from Kanzi Engine. From now on, Kanzi applies multisampling only when you use Renderbuffer blit or explicitly accessible samples. Rendering results are visible, as this option targeted legacy GPUs.

  • Modified the application configuration to accept command line parameters with double dash prefix as is common practice. The new parameters for selecting graphics backend are:

    • --gles

    • --opengles

    • --gl

    • --opengl

    • --vk

    • --vulkan

    The new parameters for selecting windowing system are:

    • --egl

    • --wgl

    • --glx

    You can use the same parameters without the double dashes in an application configuration file.

Changes to the CompositionStack

Simplified the use of the CompositionStack to require use of an instance owned by Renderer.

Removed

Use instead

  • kanzi::CompositionStack::apply3D

  • kanzi::CompositionStack::applyColorBlend2D

  • kanzi::CompositionStack::applyColorBlend3D

  • kanzi::CompositionStack::applyComposition2D

  • kanzi::CompositionStack::applyComposition3D

  • kanzi::CompositionStack::applyDepthStencil2D

  • kanzi::CompositionStack::applyDepthStencil3D

  • kanzi::CompositionStack::applyRasterization2D

  • kanzi::CompositionStack::applyRasterization3D

Changes to State Manager

Changed how a State Manager sends property change notifications and updates bindings on a state change. Previously every state change sent one notification when removing the properties of the old state, and one notification when adding the properties of the new state. Now a state change sends only one notification with the new property values of the new state. If a state change has a transition animation, during the transition Kanzi sends property notifications as before, but does not send the redundant notifications caused by the state change in the beginning of transition.

When you create a State Manager using the API:

Changes to properties and bindings

String conversions of Boolean values in properties and bindings now result in lower case true or false instead of 1 or 0, and True or False.

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

Changes to suspension handling

Added the WakeupSignalSource class with functionality that replaces these removed functions:

  • EventSource::getNativeEventHandle

  • KeyMapEventFilter::getNativeEventHandle

  • KeyRepeatGenerator::getNativeEventHandle

Changes to event handling

Added the Application::setInputEventHandle function that replaces the functionality removed from Application::appendEventSource.

Changes to kzuEngine

Removed the previously deprecated functionality related to kzuEngine:

  • Application::getEngine function

  • Application::m_engine member

  • kzuEngine struct

  • All functions starting with kzuEngine

  • The kzu_engine.h header file

Changes to Scroll View messages

Removed these deprecated messages and message handlers that were used by the Scroll View and Grid List Box nodes:

Removed

Use instead

ScrollViewConcept::ScrollDirectionMessage

ScrollViewConcept::ScrollEdgeMessage

ScrollViewConcept::ScrollPageMessage

See Scrolling functionality.

Changes to several Kanzi Engine APIs

Updated the parameters and return types of several Kanzi Engine APIs to use the size_t data type, instead of the unsigned int.

Changed kanzi::optional and kanzi::string_view to C++17 std implementations. Migrate the parameter and return type of these classes on platforms that used Boost implementation in the previous version of Kanzi.

Changed kanzi::byte to C++17 std implementation. Migrate the parameter and return type of these classes on platforms that used unsigned char in the previous version of Kanzi.

Changes to C wrapper headers

Removed the headers kzs_string.hpp, kzs_arg.hpp, and kzs_memory.hpp.

Removed

Use instead

kzsStrcat

kzsStrncmp

and so on

strcat

strncmp

and so on

kzsStringFormatList

kzsStringFormatGetLength

kanzi::format

kzsStringFindNextCharacter

string_view::find

kzsStringGetUTF8ByteCount

kzsStringWriteUnicodeCharacter

kzsStringGetUnicodeCharacter

stringToUnicodeVector

Changes to legacy file API

Removed the headers kzs_file.hpp and kzs_resource_file.hpp.

Use ReadOnlyDiskFile instead.

Changes to focus messages

Removed these deprecated messages and message handlers that were used by the focus system:

Removed

Use instead

ScopeBroughtToFrontMessage

FocusManager::OverlayBroughtToFrontMessage

ScopeSentToBackMessage

FocusManager::OverlaySentToBackMessage

See Changes in focus handling.

Changes to Android NDK version

To set your Kanzi application to use the current Android NDK version, in your application build.gradle file set ndkVersion to 26.3.11579264.

Changes to Kanzi Studio Android package export

When building an Android package from Kanzi Studio, Kanzi Studio now exports the cfg file based on the project Binary File Name property.

To migrate your application, update the definition of binaryFileName or kzbPathList.

Deprecation of Page and Page Host Nodes

The Page and Page Host nodes are deprecated and will be removed in the next version of Kanzi. To create navigable user interfaces, you must manually recreate your Kanzi Studio project and Kanzi applications to use the Activity and Activity Host nodes instead.

To create and inspect Activity Host and Activity nodes, and to simulate Activity activation, use the Activity Browser window. See Using the Activity Browser.

Use these Activity Host nodes to replace the Page Host nodes:

  • An Exclusive Activity Host can have only one of its child Activities active at a time. When one child Activity of an Exclusive Activity Host is active, all other Activities of that Activity Host are inactive. For example, you can use an Exclusive Activity Host to toggle between views in your application.

    See Exclusive Activity Host.

  • Parallel Activity Host can activate more than one of its child Activities at a time. When you activate an Activity, a Parallel Activity Host brings that Activity to the front.

    See Parallel Activity Host.

  • You can use a list data source and a Data-Driven Exclusive Activity Host to create parts of UI with Activities from content of data objects. For example, you can define the content of menus in a data source and use a Data-Driven Exclusive Activity Host to create the menus in your application.

    See Data-Driven Exclusive Activity Host.

Replace Page nodes with Activity nodes.

To learn about Activities, see:

Changes to text rendering

Changes to morph data

Previous versions of Kanzi used a separate kanzi::Morph object that inherited Mesh and referred to other meshes as morph targets to blend to and from. Since Kanzi version 4.0.0-beta2 morph data is expressed as differences against the base mesh. The use of multiple meshes have been removed, as has the whole kanzi::Morph class concept.

Meshes may now contain an internal Mesh::MorphData object that contains the differential data. This data can be accessed by const kanzi::Mesh::MorphData* kanzi::Mesh::getMorphData() const. For morphs with sufficiently small amount of shapes that fit the common 16 attribute channel limit, Kanzi Studio will export the mesh data as a vertex buffer blob within Mesh::MorphData. Morph data requiring more channels will be stored as a data texture assigned directly to Model3D based on morph shapes selected for use.

Shaders using old morph fixed uniforms kzMorphDataTexture, kzMorphIndices and kzMorphWeights are now marked deprecated in Studio.

Changes to morph weights

In 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 kanzi::Morph. Since Kanzi 4.0.0-beta1, morph weights are preserved.

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

In previous version of Kanzi, morph weights were handled by a separate morph runtime that was a child object of a kanzi::Model3D node. Since Kanzi 4.0.0-beta1, morph weights are simply a range.

To set morph weights, assign an AbstractRangeSharedPtr that contains a kanzi::TypedValueRange<float> with the correct amount of elements into Model3D::MorphingProperty. The maximum amount of weights can be read from Mesh::MorphData.

Even if no weigths have been assigned, Kanzi Engine creates a class value source filled with the default weights that will be used as long as the application developer has not assigned a higher-level value or binding.

The previus mechanism for animating morph weights using kanzi::MorphWeightAnimationTimeline has been deprecated. Since the morph weights are now simply a range property, use the newly introduced type RangeIndexAnimationTimeline.

Removed

Use instead

  • kanzi::Model3D::MorphRuntime (specialized class)

  • kanzi::MorphWeightAnimationTimeline

Changes to CubeMapRenderPass

CubeMapRenderPass no longer automatically creates a depth texture. To create a depth texture, set the CubeMapRenderPass::DepthFormatProperty.

Unless you set CubeMapRenderPass::DepthFormatProperty, or you manually set a depth texture using the CubeMapRenderPass::DepthTargetProperty, to save memory and improve performance, Kanzi uses only one depth renderbuffer. Kanzi reuses this depth renderbuffer for each face in the CubeMapRenderPass.

Changes to Tags

The NodeList filtering performance using tags has been significantly improved, in cases where the node lists and the tags are not changing. If no changes are detected, the filtering phase can be skipped altogether.

To check for a tag in node, instead of PropertyObject::getProperty, use kanzi::Node::hasTag. Tags are still set as boolean properties and can be bound to and set using StateManager or bindings. The properties are no longer inheritable, and the tag state is maintained separately in the node hierarchy.

The tags now have an associated change flag type PropertyTypeChangeFlag::PropertyTypeChangeFlagTag. This is automatically set by Studio when exporting projects. The user needs to export existing projects for the tag changes to take effect.

The helper class kanzi::Tag has been removed. To create new tags or access existing tags, use Node::acquireTag. To manipulate tags, either use the property interface or the helper functions Node::setTag and Node::removeTag.

Changes to Texture

The obsolete create info types kanzi::Texture::CreateInfoNode2DRenderTarget and Texture::CreateInfoRenderpassRenderTarget have been removed. Use Texture::CreateInfoRenderTarget. Textures used for composition now always either contain their own framebuffers, or are internally combined by Kanzi into a single framebuffer, for example in CompositionTargetRenderPass. The specific separate creation scenarios are removed as unnecessary.

Changes to Kanzi Studio commands

  • Changed SaveProject to accept directory path instead of file path. Replace SaveProject "C:\Example\directory\path\projectName.kzproj" with SaveProject "C:\example\directory\path\", or alternatively with SaveProject to save the project to its existing location. See SaveProject.

  • Changed NewProject to accept directory path instead of file path. Replace NewProject "C:\Example\directory\path\projectName.kzproj" with NewProject "C:\example\directory\path\" "projectName". See NewProject.

Removed API members

Removed these Kanzi Engine C++ API members that were deprecated in earlier versions of Kanzi:

Removed

Use instead

Application::getInputManager

Screen::getInputManager

FocusManager::createFocusScopeInfo

FocusScope::create

FocusManager::isFocusFence

FocusManager::getFocusScopeType

FocusManager::isFocusScope

FocusManager::getFocusScopeType

FocusManager::setFocusFence

FocusManager::setFocusScopeType

FocusManager::setFocusScope

FocusManager::setFocusScopeType

FocusManager::trySetActiveFocus

FocusManager::trySetFocus

FocusManager::tryMoveActiveFocus

FocusManager::tryMoveFocus

InputManipulator::getTouchEventRoutingMode

InputManipulator::getEventRoutingMode

InputManipulator::setTouchEventRoutingMode

InputManipulator::setEventRoutingMode

Keyboard

KeyManipulator

rayPickHitTest(const Vector2& limits, OverlayScope& scope, Scene* scene, Camera* camera, int x, int y)

rayPickHitTest

KzuInputTouchPoint

TouchPoint

Light::isEnabled

Node::isVisible

Light::setEnabled

Node::setVisible

Node2D::setLayoutSize

Node2D::setSize

collectResourceUrlsFromPrefabTemplateNodeResourceDictionaryUrls

Not available

NodeComponent::NodeComponentMessageArguments

NodeComponent::NodeComponentTargetMessageArguments

InputManipulator::TouchEventRoutingMode

InputManipulator::EventRoutingMode

PopupScope

AutoClosingModalScope

See also

Kanzi 4 beta release notes

Known issues