Application configuration reference

You can configure your Kanzi application:

• In the C++ application in the onConfigure() function.
• In application.cfg by setting the parameters for Kanzi Studio projects with or without C++ application.

While you can configure your Kanzi application in the onConfigure() function, in application.cfg you can configure some parameters without recompiling your application or even without a C++ application. The configuration you specify in application.cfg overrides the configuration you specify in onConfigure().

For example, in application.cfg you can tell your Kanzi application which kzb file to load, enable performance information in your application, and set how many threads you want to use for loading the application resources.

See Configuring your application.

You can use these application configuration settings.

Loading

BinaryName

You can set which kzb file or configuration file your Kanzi application loads when you launch your Kanzi application.

See Using kzb files.

# Loads the kzb file named MyApplication.kzb.
BinaryName = "MyApplication.kzb"

# Loads the binary configuration file MyApplicationKzbs.cfg that lists
# all kzb files that your Kanzi application loads.
BinaryName = "MyApplication.kzb.cfg"

// Loads kzb file named MyApplication.kzb.
configuration.binaryName = "MyApplication.kzb";

// Loads the binary configuration file MyApplicationKzbs.cfg that lists
// all kzb files that your Kanzi application loads.
configuration.binaryName = "MyApplication.kzb.cfg";

ModuleNames

You can set which plugins your Kanzi application loads when you launch your Kanzi application.

# Loads the plugin DLL files MyPlugin1.dll and MyPlugin2.dll.
ModuleNames = "MyPlugin1; MyPlugin1"

// Loads the plugin DLL files MyPlugin1.dll and MyPlugin2.dll. 
configuration.moduleNames = {"MyPlugin1", "MyPlugin1"};

LoadingThreadCount

When users run your Kanzi application in an environment with a multi-core processor, Kanzi automatically uses multiple CPU cores to load the GPU resources in the kzb files to RAM. See Loading resources in parallel.

GPU resources Kanzi loads in parallel include all types of textures, shaders, and meshes. To deploy these resources from RAM to GPU memory and to load prefab templates, Kanzi always uses the main thread. See Images and textures best practices, Shaders best practices, Meshes best practices.

# Switches off the use of multiple cores for loading your application.
# Loads your application resources using the main thread.
LoadingThreadCount = 0

# Uses six threads to load your application.
LoadingThreadCount = 5

// Switches off the use of multiple cores for loading your application.
// Loads your application resources using the main thread.
configuration.loadingThreadCount = 0;

// Uses six threads to load your application.
configuration.loadingThreadCount = 5;

MaxPendingResources

You can set the maximum number of resources that the loading threads process at the same time. By increasing the number of resources you can speed up the loading, but at the same time you increase the peak memory use during loading because you can load more resources to the memory before they are deployed to the GPU.

# Sets the maximum number of resources processed by the loading
# threads to the number of loading threads + 1. This is the default value.
MaxPendingResources = 0

# Sets the maximum number of resources processed by the loading
# threads to 20 resources.
MaxPendingResources = 20

// Sets the maximum number of resources processed by the loading
// threads to the number of loading threads + 1. This is the default value.
configuration.maxPendingResources = 0;

// Sets the maximum number of resources processed by the loading
// threads to 20 resources.
configuration.maxPendingResources = 20;

UseMemoryMappedLoading

When running your Kanzi application on an operating system that supports memory mapping of files, you can enable memory mapped loading for the kzb files your Kanzi application uses. When you enable memory mapped loading you can reduce the loading times of your Kanzi application because it reduces the amount of file accesses.

Memory mapping of files is supported, for example, on Windows, Linux, and QNX operating systems. Before enabling memory mapped loading, check that it is supported on the platform running your Kanzi application.

To check whether memory mapped loading is supported on your platform, call the kzsMemoryMappedFileIsSupported() function. The function returns True if memory mapped loading is supported, and False if it is not supported.

If you enable memory mapped loading on a platform that does not support this feature, Kanzi shows a warning and uses regular file access for loading the kzb files.

# Enables the memory mapped loading for the kzb files in your Kanzi application.
UseMemoryMappedLoading = 1

// Enables the memory mapped loading for the kzb files in your Kanzi application.
configuration.useMemoryMappedLoading = 1;

Performance

ApplicationIdleState

Kanzi suspends the main loop when there is no input, tasks, timers, animations, or when there is nothing in the application that updates the rendering. See Application idle state.

When using application idle state, consider these use cases:

• If your Kanzi application is showing an animation, Kanzi by default throttles the CPU to the maximum FPS. If there are no animations, Kanzi sets the application to idle state. For this reason to conserve the CPU and power, Kanzi by default limits the maximum frame rate to 60 frames per second. Use the application configuration to set the maximum frame rate for your application. See MaximumFPS.
• If your application relies on continuously calling Application::updateOverride, disable the application idle state.

# Disables the application idle state.
ApplicationIdleState = 0

// Disables the application idle state.
configuration.applicationIdleStateEnabled = 0;

MaximumFPS

You can limit the number of frames rendered per second by setting the maximum frame rate.

If your Kanzi application is showing an animation, Kanzi by default throttles the CPU to the maximum FPS. If there are no animations, Kanzi sets the application to idle state. For this reason to conserve the CPU and power, Kanzi by default limits the maximum frame rate to 60 frames per second. Use the application configuration to set the maximum frame rate for your application.

See PerformanceInfoLevel.

# Sets the maximum application frame rate to 32 frames per second.
MaximumFPS = 32

# Disables the limit.
MaximumFPS = 0

// Sets the maximum application frame rate to 32 frames per second.
configuration.frameRateLimit = 32;

// Disables the limit.
configuration.frameRateLimit = 0;

PerformanceInfoLevel

You can enable the display of Performance HUD that shows the performance information for your Kanzi application. Use the Performance HUD to see how your application performs on target devices and to find performance bottlenecks.

Performance HUD shows this performance information for your Kanzi application:

• FPS shows the number of frames rendered every second.
• Last Frame shows this information for the last frame:
  • Time shows the time in milliseconds it took to render the frame.
  • Batch Count shows how many individual draw calls were executed (glDrawElements and glDrawArrays).
    You can access the batch count using the Kanzi Engine API by calling getBatchCount().
  • Triangle Count shows how many individual triangles were drawn in total during a frame.
    You can access the triangle count in the Kanzi Engine API by calling getTriangleCount().
  • Texture Switches shows how many times a new texture was bound to GPU.
    You can access the texture switch count in the Kanzi Engine API by calling getTextureSwitchCount().
  • FBO Switches shows how many framebuffer objects were bound to GPU. See Rendering best practices.
    You can access the buffer switch count in the Kanzi Engine API by calling getFramebufferSwitchCount().
  • Timeline Clock shows the time in milliseconds it took to execute all animations in the application.
• Shader shows how many times a new shader was bound for the newly applied batch and how many individual shader uniforms were sent for the last frame. See Reducing shader switches.
  You can access the shader switch count in the Kanzi Engine API by calling getShaderSwitchCount().
  You can access the uniforms sent in the Kanzi Engine API by calling getUniformSendCount().
• Resource Memory Usage shows an estimated amount of local GPU memory (VRAM) and non-local GPU memory (RAM) that your Kanzi application uses.
  The values that the Performance HUD shows in the Kanzi Studio Preview and when you run the Kanzi application on a target device differ because Kanzi Studio loads and keeps in memory all resources in the application.

See Best practices.

# Enables the full Performance HUD in a Kanzi application.
PerformanceInfoLevel = 2

// Enables the full Performance HUD in a Kanzi application.
configuration.performanceInfoLevel = ApplicationProperties::PerformanceInfoLevelFull;

ProfilingCategoryFilter

You can control the state of performance profiling categories that you use to group performance profilers, and set which profilers you want to show in the Performance HUD. See Measuring application performance.

# Enables the full Performance HUD.
PerformanceInfoLevel = 2
# Enables performance profiling for animations running in the main loop and shows the performance graph in the Performance HUD.
ProfilingCategoryFilter="MainLoopAnimation=show"

# Enables the MyFunctionProfiler category and disables the MainLoopRendering category.
ProfilingCategoryFilter="MyFunctionProfiler=on;MainLoopRendering=off"

# Enables all performance profiling categories.
ProfilingCategoryFilter="*=on"

# Enables categories Generic and MyProfilingCategory.
ProfilingCategoryFilter="Generic|MyProfilingCategory=on"

# Enables resource profiling. See Measuring the loading and deployment time of resources.
ProfilingCategoryFilter="ResourceLoading=on"

// Enables the full Performance HUD.
configuration.performanceInfoLevel = ApplicationProperties::PerformanceInfoLevelFull;
// Enables performance profiling for animations running in the main loop and shows the performance graph in the Performance HUD.
configuration.profilingCategoryFilter = "MainLoopAnimation=show";

# Enables the MyFunctionProfiler category and disables the MainLoopRendering category.
configuration.profilingCategoryFilter="MyFunctionProfiler=on;MainLoopRendering=off"

// Enables all performance profiling categories.
configuration.profilingCategoryFilter = "*=on";

// Enables categories Generic and MyProfilingCategory.
configuration.profilingCategoryFilter = "Generic|MyProfilingCategory=on";

// Enables resource profiling. See Measuring the loading and deployment time of resources.
configuration.profilingCategoryFilter = "ResourceLoading=on";

This table lists the Kanzi startup performance profiling categories and profilers that are included in the Profiling build.

This table lists the Kanzi main loop task performance profiling categories and profilers that are included in the Profiling build.

Glyph cache texture size

When you use a Text Block Kanzi creates a glyph cache texture for every font and font size combination. You can set the height and width of glyph cache textures to adjust the size of the glyph cache texture either when it gets full, or to optimize the performance of your Kanzi application.

Because larger glyph cache textures use more VRAM, try different sizes before you set the final size . The upper limit of the glyph cache texture size depends on the GPU, but usually it is 2048 by 2048 pixels. The default size of the glyph cache texture is 512 by 512 pixels.

Kanzi applies the size of the glyph cache texture to all glyph cache textures.

# Sets the glyph cache texture height to 768, and width to 1024 pixels.
GlyphCacheHeight = 768
GlyphCacheWidth = 1024

// Sets the glyph cache texture height to 768, and width to 1024 pixels.
configuration.glyphCacheHeight = 768;
configuration.glyphCacheWidth = 1024;

Graphics performance logging

GraphicsLoggingEnabled

You can enable Kanzi to print to the debug console the graphics API calls of your application in the Application::onConfigure() function, in the application.cfg, or using the command line argument, if your target supports command line arguments.

On the command line use:

• -log-graphics to log the graphics API calls

# Enables the logging of the graphics API calls.
GraphicsLoggingEnabled = 1

// Enables the logging of the graphics API calls.
configuration.graphicsLoggingEnabled = 1;

LogOpenGLExtensions

You can enable Kanzi to print to the debug console a list of the graphics-related extensions on application startup.

# Enables the logging of the graphics-related extensions.
LogOpenGLExtensions = 1

// Enables the logging of the graphics-related extensions.
configuration.extensionOutputEnabled = 1;

LogOpenGLInformation

You can enable Kanzi to print to the debug console this graphics-related information on application startup:

• GL vendor
• GL renderer
• GL version
• Shading language version

# Enables the logging of the graphics-related information.
LogOpenGLInformation = 1

// Enables the logging of the graphics-related information.
configuration.informationOutputEnabled= 1;

LogSurfaceInformation

You can enable Kanzi to print to the debug console these graphics-related properties on application startup:

• Requested and acquired surface properties. See Surface properties.
• Size of the entire desktop and each display.
• Size of the application window. See Application window position and size.

# Enables the logging of the graphics-related properties.
LogSurfaceInformation = 1

// Enables the logging of the graphics-related properties.
configuration.propertyOutputEnabled= 1;

Graphics library

On the Windows operating system you can select whether you want to use ES or GL in the Application::onConfigure() function, in the application.cfg, or using the command line arguments, if your target supports command line arguments.

On the command line use:

• -gles to use ES
• -gl to use GL
• -egl to use EGL
• -wgl to use WGL

# Sets the surface target for OpenGL rendering and WGL graphics context.
GraphicsBackend = opengl

// Sets the surface target for OpenGL rendering and WGL graphics context.
configuration.defaultSurfaceProperties.type = KZS_SURFACE_TYPE_GL_ONLY;

Surface properties

Surface properties control the properties of the hardware accelerated graphics surface on which Kanzi renders. They control the relation between image quality and rendering speed. The surface properties you set are considered requests to be matched by the graphics system of the target hardware. Whether a given request is considered an upper bound, a lower bound, or an exact value is platform dependent.

The default values of surface properties are platform dependent. You can get them by calling kzsSurfaceGetDefaultProperties().

# An example configuration for a typical high-speed rendering application
SurfaceBitsStencil = 1
SurfaceBitsDepthBuffer = 16
SurfaceBitsRed = 5
SurfaceBitsGreen = 6
SurfaceBitsBlue = 5
SurfaceBitsAlpha = 0
SurfaceSamplesAntialiasing = 0

# An example configuration for a high image quality application
SurfaceBitsStencil = 8
SurfaceBitsDepthBuffer = 24
SurfaceBitsRed = 8
SurfaceBitsGreen = 8
SurfaceBitsBlue = 8
SurfaceBitsAlpha = 8
SurfaceSamplesAntialiasing = 4

// An example configuration for a typical high-speed rendering application
configuration.defaultSurfaceProperties.bitsStencil = 1;
configuration.defaultSurfaceProperties.bitsDepthBuffer = 16;
configuration.defaultSurfaceProperties.bitsColorR = 5;
configuration.defaultSurfaceProperties.bitsColorG = 6;
configuration.defaultSurfaceProperties.bitsColorB = 5;
configuration.defaultSurfaceProperties.bitsAlpha = 0;
configuration.defaultSurfaceProperties.antiAliasing = 0;

// An example configuration for a high image quality application
configuration.defaultSurfaceProperties.bitsStencil = 8;
configuration.defaultSurfaceProperties.bitsDepthBuffer = 24;
configuration.defaultSurfaceProperties.bitsColorR = 8;
configuration.defaultSurfaceProperties.bitsColorG = 8;
configuration.defaultSurfaceProperties.bitsColorB = 8;
configuration.defaultSurfaceProperties.bitsAlpha = 8;
configuration.defaultSurfaceProperties.antiAliasing = 4;

Application window position and size

You can set the position of the application on the screen relative to the upper-left corner of the screen and the size of the application window in pixels. The default size of the window is 640x480 pixels and center of the device screen.

When you run your Kanzi application in full-screen mode on a system with more than one display, you can set the default display where your Kanzi application window appears.

Note that in order to use the default application display, you have to set the window style of your Kanzi application to full-screen.

To make the application window fixed size, resizable, fullscreen, or without borders, see Application window style.

# Set the width to 1280 and height to 720 pixels and place it 100 pixels
# from the top and 1 pixel from the left side of the device screen.
WindowWidth = 1280
WindowHeight = 720
WindowX = 100
WindowY = 1

# Place the application window in the top-left corner of the device screen.
WindowX = 0
WindowY = 0

# Sets the second display as the default display for the full-screen application window.
DefaultDisplayIndex = 1

# On Windows, places the application window on top of other windows.
WindowOrder = 0

// Set the width to 1280 and height to 720 pixels and place it 100 pixels
// from the top and 1 pixel from the left side of the device screen.
configuration.defaultWindowProperties.width = 1280;
configuration.defaultWindowProperties.height = 720;
configuration.defaultWindowProperties.x = 100;
configuration.defaultWindowProperties.y = 1;

// Place the application window in the top-left corner of the device screen.
configuration.defaultWindowProperties.x = 0;
configuration.defaultWindowProperties.y = 0;

// Sets the second display as the default display for the full-screen application window.
configuration.defaultWindowProperties.defaultDisplayIndex = 1;

// On Windows, places the application window on top of other windows.
configuration.defaultWindowProperties.order = 0;

Application window style

You can set the style of the window of your Kanzi application. Besides the default window with a border that users can resize, you can set your Kanzi application to launch in a window without a border, in a window of fixed size, and in a window that occupies the entire device screen.

To set the position and size of the application window, see Application window position and size.

# Launch the application in a window that occupies the whole screen of the device.
WindowStyle = "fullscreen"

// Launch the application in a window that occupies the whole screen of the device.
configuration.defaultWindowProperties.style = KZS_WINDOW_STYLE_FULL_SCREEN;

Input handling

You can define how your application handles touch and pointer input. When you run your application on a device, you can set whether the application reacts to the pointer of the device, uses a touch screen, or both. You can also set the transformation matrix of the input event coordinates.

InputTransform

You can set the transformation matrix of the input event coordinates. This transformation only affects input event coordinates, not the orientation of the Kanzi application screen . For example, use this to rotate the touch screen in relation to your application screen.

In application.cfg	InputTransform = transformation
In onConfigure()	configuration.defaultEventSourceProperties.transformation = transformation;
Values	transformation Transformation matrix of the touch screen.
application.cfg example	# Rotate a touch screen sized 1280x720 pixels by 180 degrees. InputTransform = -1, 0, 0, 0, -1, 0, 1280, 720, 1
onConfigure() example	// Rotate a touch screen sized 1280x720 pixels by 180 degrees. configuration.defaultEventSourceProperties.transformation = Matrix3x3::createTranslation(1280, 720) * Matrix3x3::createRotationInDegrees(180.0f);
	The examples use this equation to calculate the transformation matrix:

InputTranslation

You can set how Kanzi translates pointer and touch events.

# Translate pointer events to touch events.
InputTranslation = PointerToTouch

// Translate pointer events to touch events.
configuration.defaultEventSourceProperties.translation = KZS_INPUT_TRANSLATE_POINTER_TO_TOUCH;

InputDiscardPointer

You can set whether the application reacts to the pointer of the device.

# Ignore pointer input.
InputDiscardPointer = 1

// Ignore pointer input.
configuration.defaultEventSourceProperties.discardPointerEvents = 1;

InputDiscardTouch

You can set whether the application reacts to touch input.

# Ignore touch input.
InputDiscardTouch = 1

// Ignore touch input.
configuration.defaultEventSourceProperties.discardTouchEvents = 1;

Input event devices on Linux

You can configure the input event devices that Kanzi listens to on Linux ports where the native windowing system does not provide input device handling. This way Kanzi can listen to events directly from the input event devices provided by the operating system.
For example, in Vivante fbdev and WSEGL ports you can configure the input event devices that Kanzi listens to. In X11 and Wayland ports the native windowing system handles input devices.

Kanzi by default listens to all input event devices named eventN, where N is an integer, in the /dev/input directory.

# Listens to events from one input event device.
InputEventDevice = "/dev/input/event1"

# Listens to events from two input event devices.
InputEventDevice = "/dev/input/event0;/dev/input/event1"

# Disables listening to events from input event devices.
InputEventDevice = "none"

// Listens to events from one input event device.
configuration.defaultEventSourceProperties.inputEventDevice = "/dev/input/event1";

// Listens to events from two input event devices.
configuration.defaultEventSourceProperties.inputEventDevice = "/dev/input/event0;/dev/input/event1";

// Disables listening to events from input event devices.
configuration.defaultEventSourceProperties.inputEventDevice = "none";

See also

Configuring your application

Best practices

Loading resources in parallel

Using kzb files

Open topic with navigation