Application configuration reference¶
You can configure your Kanzi application:
In the C++ application override the
Application::onConfigurefunction of your application class. Kanzi calls this function as part of application initialization before it reads theapplication.cfgand before it initializes the graphics subsystem. Use this function to configure application properties.In
application.cfgby setting the parameters for Kanzi Studio projects without recompiling your application or even without a C++ application.
The configuration you specify in application.cfg overrides the configuration you specify in Application::onConfigure.
Setting which application.cfg to use¶
When you have more than one Kanzi application executable file in a directory, you can set a separate configuration file for each executable.
To set which application.cfg to use when running your Kanzi application from the command line, enter the name of the application executable file followed by the -config option, and the name of the configuration file.
For example, to run a Kanzi application named MyApplication with the myConfiguration.cfg file use
MyApplication.exe -config=myConfiguration.cfg
Using the application.cfg¶
To configure your Kanzi application using application.cfg, create an application.cfg file that contains the parameter names and their values in:
<ProjectName>/Application Playerif you have a Kanzi Studio project without a C++ application<ProjectName>/Application/binif you have a Kanzi Studio project with a C++ application
When you launch your Kanzi application, the application uses the parameters in the application.cfg to configure your application.
Error handling for application.cfg¶
If an application.cfg is missing or is corrupted, Kanzi application logs a corresponding error message and continues to run with the default settings.
If you want to implement your own application.cfg error handling, you can create a custom logger to detect such errors. See Creating a custom logger.
Running an application without reading the application.cfg¶
On some embedded platforms reading the application.cfg file can have a performance impact.
To run an application without reading the application.cfg file, on the command line launch your Kanzi application with the -config="" option.
For example, to run a Kanzi application named MyApplication without reading the application.cfg file use
MyApplication.exe -config=""
Loading¶
BinaryName¶
You can set which kzb file or kzb configuration file your Kanzi application loads when you launch your Kanzi application.
See Kzb files.
In |
|
||
|
|||
Value |
|
||
|
# Loads the kzb file named my_application.kzb.
BinaryName = "my_application.kzb"
# Loads the kzb configuration file my_application.kzb.cfg that lists
# all the kzb files that your Kanzi application loads.
BinaryName = "my_application.kzb.cfg"
|
||
|
// Loads the kzb file named my_application.kzb.
configuration.binaryName = "my_application.kzb";
// Loads the kzb configuration file my_application.kzb.cfg that lists
// all the kzb files that your Kanzi application loads.
configuration.binaryName = "my_application.kzb.cfg";
|
FontEngine¶
You can set which font engine you want to load at application startup to render the text in your application:
FreeType uses the FreeType rasterizer, HarfBuzz shaper, and ICU bidirectional library, and libunibreak for line breaking. This is the default font engine.
iType uses the Monotype iType rasterizer and WorldType® Shaper™ for shaping.
When you do not load a font engine, Kanzi does not render the text in your application.
When loading a font engine, keep in mind that:
In a static build, you must statically link to the application the font engine that you want to load.
In a dynamic build, Kanzi loads the font engine library.
You can also set which font engine you want the Kanzi Studio Preview to use to render text. See Setting the font engine for the Preview.
In |
|
||
|
|||
Values |
|
||
|
# Load the iType font engine at application startup.
FontEngine = IType
|
||
|
// Load the iType font engine at application startup.
configuration.fontEngine = ApplicationProperties::FontEngine::IType;
|
Font engine dictionaries¶
You can customize how Kanzi iType font engine wraps words in Thai text by setting a Thai dictionary that you want to use instead of the one that is built into the iType font engine.
See Customizing word wrapping in Thai text with iType font engine.
In |
|
||||
|
|||||
Values |
|
||||
|
# Set additional backend dictionaries.
ITypeDictionaryUrls = file:///usr/share/itype/thai-dictionary.wtd
|
||||
|
// Set additional backend dictionaries.
configuration.fontEngineDictionaryUrls[ApplicationProperties::FontEngine::IType] = "file:///usr/share/itype/thai-dictionary.wtd";
|
ModuleNames¶
You can set which plugins your Kanzi application loads when you launch your Kanzi application.
In |
|
||
|
|||
Values |
|
||
|
# Loads the plugin DLL files MyPlugin1.dll and MyPlugin2.dll.
ModuleNames = "MyPlugin1; MyPlugin2"
|
||
|
// Loads the plugin DLL files MyPlugin1.dll and MyPlugin2.dll.
configuration.moduleNames = {"MyPlugin1", "MyPlugin2"};
|
DeploymentQueueBudget¶
Kanzi keeps a queue of resources that are deployed on the UI thread. Use DeploymentQueueBudget to control the amount of time that Kanzi spends each frame to deploy resources. When many small resources are in the deployment queue, time budget greater than 0 can significantly decrease the time to load application resources.
The time budget does not set a hard limit on the total amount of time spent on resource deployment each frame. A long running deployment task can take longer than the allocated time.
When set to the default value of 0 milliseconds, Kanzi deploys each frame only one resource from the resource deployment queue.
See Balancing between UI responsiveness and resource loading.
In |
|
||
|
|||
Values |
|
||
|
# Each frame Kanzi spends up to 2 milliseconds to deploy resources.
# Kanzi keeps deploying resources until it spends the allocated time budget
# for that frame.
DeploymentQueueBudget = 2
|
||
|
// Each frame Kanzi spends up to 2 milliseconds to deploy resources.
// Kanzi keeps deploying resources until it spends the allocated time budget
// for that frame.
configuration.deploymentQueueBudget = 2;
|
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.
In |
|
||
|
|||
Values |
|
||
|
# 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.
In |
|
||
|
|||
Values |
|
||
|
# 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;
|
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.
When using application idle state, consider that:
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 executing some main loop tasks, such as functionality that you added to the main loop
UserStage, disable the idle state.When your application is in idle state and the application makes changes to the render pass tree, Kanzi does not trigger the rendering to render the changes. To render the changes in such case, you must manually trigger the rendering by calling on any node the
Node::invalidateDrawfunction.
In |
|
||||
|
|||||
Values |
|
||||
|
# 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.
In |
|
||
|
|||
Value |
|
||
|
# 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:
Main Loop Counter shows the number of times that the Kanzi main loop has run.
Time shows the time in milliseconds it took to render the frame.
Draw Count shows how many individual draw calls were executed.
Triangle Count shows an estimated total of individual triangles drawn during a frame.
Pipeline Count shows how many times a new render pipeline was bound for the last frame. See Reducing shader switches.
Pass Count shows how many render passes were used in the last frame. See Rendering best practices.
Memory Upload shows how many bytes of rolling staging memory were used on the last frame as well as the total buffer size. Staging memory contains uniform data and temporary storage used for updating GPU resources like vertex buffers or textures. On some platforms unique buffers are used for each type of data.
Dispatch Count shows how many compute dispatches were used in the last frame.
Timeline Clock shows the time in milliseconds it took to execute all animations in the application.
Resource Memory Use 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.
Timer subscriptions shows the number of registered timer handlers in the
MessageDispatcher. Too many timer handlers can decrease the performance of your application.You can access the number of timer subscriptions in the Kanzi Engine API by calling
getSubscriptionCount().Animations shows the number of active and all animations in your Kanzi application.
You can access the number of animations in the Kanzi Engine API:
To get the number of active animations, use
getActiveTimelinePlaybackCount().To get the number of all animations, use
getTimelinePlaybackCount().
You can set the position of the Performance HUD inside the window of your Kanzi application. See PerformanceInfoPosition.
See Best practices.
In |
|
||
|
|||
Values |
|
||
|
# Enables the full Performance HUD in a Kanzi application.
PerformanceInfoLevel = 2
|
||
|
// Enables the full Performance HUD in a Kanzi application.
configuration.performanceInfoLevel = ApplicationProperties::PerformanceInfoLevelFull;
|
PerformanceInfoPosition¶
You can set the position of the Performance HUD inside the window of your Kanzi application. To see the Performance HUD in the window of your Kanzi application, you must enable it. See PerformanceInfoLevel.
In |
|
||||
|
|||||
Value |
|
||||
|
# Position the Performance HUD 100 pixels from the left side and
# 20 pixels from the top of the Kanzi application window.
PerformanceInfoPositionX = 100
PerformanceInfoPositionY = 20
|
||||
|
// Position the Performance HUD 100 pixels from the left side and
// 20 pixels from the top of the Kanzi application window.
configuration.performanceInfoProperties.positionX = 100;
configuration.performanceInfoProperties.positionY = 20;
|
PerformanceInfoGraphFilter¶
You can choose which main loop tasks you want to show as graphs in the Performance HUD. For the names of the default main loop tasks, in the application.hpp see the implementation of Application::initializeMainLoopTasks(). To see the Performance HUD in the window of your Kanzi application, you must enable it. See PerformanceInfoLevel.
In |
|
||
|
|||
Value |
|
||
|
# Enables graphs for tasks Render and MyCustomTask.
PerformanceInfoGraphFilter="Render;MyCustomTask"
|
||
|
// Enables graphs for tasks Render and MyCustomTask.
configuration.performanceInfoProperties.graphFilter="Render;MyCustomTask"
|
ProfilingCategoryFilter¶
You can control the state of performance profiling categories that you use to group performance profilers. See Measuring application performance and Measuring the loading and deployment time of resources.
In |
|
||||||||
|
|||||||||
Values |
Separate a list of category-state pairs with semicolons (;). |
||||||||
|
# Enables the MyProfiler category and disables the MainLoopRendering category.
ProfilingCategoryFilter="MyProfiler=on;MainLoopRendering=off"
# Enables all performance profiling categories.
ProfilingCategoryFilter="*=on"
# Enables categories Generic and MyProfilingCategory.
ProfilingCategoryFilter="Generic|MyProfilingCategory=on"
# Enables resource profiling.
ProfilingCategoryFilter="ResourceLoading=on"
|
||||||||
|
# Enables the MyProfiler category and disables the MainLoopRendering category.
configuration.profilingCategoryFilter="MyProfiler=on;MainLoopRendering=off"
// Enables all performance profiling categories.
configuration.profilingCategoryFilter = "*=on";
// Enables categories Generic and MyProfilingCategory.
configuration.profilingCategoryFilter = "Generic|MyProfilingCategory=on";
// Enables resource profiling.
configuration.profilingCategoryFilter = "ResourceLoading=on";
|
This table lists the Kanzi startup performance profiling categories and profilers that are included in the Profiling build.
Category |
Configuration name |
Profiler |
|---|---|---|
Application initialization |
|
|
Default resource registration |
|
|
Graphics initialization |
|
|
Startup kzb file opening |
|
|
Loading threads initialization |
|
|
Metadata registration |
|
|
Plugins loading |
|
|
Prefabs loading |
|
|
Prefabs instantiation |
|
|
Prefabs attachment |
|
|
Renderer reset |
|
|
Runtime assets registration |
|
|
Domain initialization |
|
|
|
||
|
||
|
MainLoopProfilingSampleBufferCount¶
You can set the sample buffer size of the main loop performance profiler that is included in the Profiling build. See Measuring the performance of Kanzi Engine and ProfilingCategoryFilter.
In |
|
||
|
|||
Values |
|
||
|
# Sets the maximum number of samples in main loop performance profilers
# to 3600.
MainLoopProfilingSampleBufferCount = 3600
|
||
|
// Sets the maximum number of samples in main loop performance profilers
// to 3600.
configuration.mainLoopProfilingSampleBufferCount = 3600;
|
Tracing¶
TracingSampleMaxMemory¶
You can control the amount of memory used by the tracing system to store tracing data. A large value allows storing of more samples before overwriting.
Tracing is disabled for Release builds.
In |
|
||
|
|||
Value |
|
||
|
# Sets the Tracing system to use 8MB.
TracingSampleMaxMemory = 8388608
|
||
|
// Sets the Tracing system to use 8MB.
configuration.tracingConfiguration.sampleMaxMemory = 8388608;
|
TracingStartupInterval¶
You can set a startup interval to automatically write a trace file to the current working directory at startup. This option provides a convenient method to record the application startup performance.
Tracing is disabled for Release builds.
In |
|
||
|
|||
Value |
|
||
|
# Triggers a startup trace after 5 seconds.
TracingStartupInterval = 5000
# Disables writing a startup trace.
TracingStartupInterval = 0
|
||
|
// Triggers a startup trace after 5 seconds.
configuration.tracingConfiguration.startupInterval = chrono::milliseconds{ 5000 };
// Disables writing a startup trace.
configuration.tracingConfiguration.startupInterval = chrono::milliseconds{ 0 };
|
TracingInterval¶
You can set the interval when Kanzi writes a trace file on a recurring basis after writing the startup trace. At every expiration of the interval, Kanzi writes a trace file to the current working directory and overwrites the previous trace file.
Tracing is disabled for Release builds.
In |
|
||
|
|||
Value |
|
||
|
# Triggers a recurring trace every 5 seconds.
TracingInterval = 5000
# Disables writing a recurring trace.
TracingInterval = 0
|
||
|
// Triggers a recurring trace every 5 seconds.
configuration.tracingConfiguration.recurringInterval = chrono::milliseconds{ 5000 };
// Disables writing a recurring trace.
configuration.tracingConfiguration.recurringInterval = chrono::milliseconds{ 0 };
|
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.
In |
|
||
|
|||
Values |
|
||
|
# 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;
|
Optimization¶
InitializePlatform¶
On the integrity_rcar_rwm_aarch64 platform you can set whether you want to initialize the application graphics. Use this approach only as a late-stage optimization when you want to manually synchronize the starting of multiple applications that initialize at the same time.
This configuration controls the initialization of the graphics driver, device window manager, and whether the display is switched on. When you disable this configuration, to enable your Kanzi application to create a window, in the same process you must initialize:
PVRGrfxServerInit()R_WM_DevInit()(Optional)
R_WM_DevInfoGet()(Optional)
R_WM_ScreenBgColorSet()R_WM_ScreenEnable()Explicitly set the application window width and height. See Application window position and size.
When you disable graphics initialization with this configuration, you must initialize graphics for each application separately where you disabled this setting.
In |
|
||||
|
|||||
Values |
|
||||
|
# Disables the graphics initialization.
InitializePlatform = 0
|
||||
|
// Disables the graphics initialization.
configuration.defaultWindowProperties.initializePlatform = 0;
|
MmapMode¶
On operating systems that support it, you can set how Kanzi instructs the system to memory map files:
Lazy mapping waits for your Kanzi application to access file contents before mapping that portion of the file.
Eager mapping maps the whole file immediately.
The behavior of the application is identical between the two strategies, but you can choose when to pay the runtime cost of mapping a file.
By default Kanzi uses the default memory mapping strategy of the system.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Uses lazy memory mapping.
MmapMode = lazy
|
||
|
// Uses lazy memory mapping.
configuration.mmapMode = MmapMode::Lazy;
|
GPU resources¶
HandleGPUResources¶
You can set how your Kanzi application handles in the paused state (MainLoopState::Paused) the GPU resources that are not stored in a kzb file.
In |
|
||
|
|||
Values |
|
||
|
# Invalidates the GPU resources.
HandleGPUResources = invalidate
|
||
|
// Invalidates the GPU resources.
configuration.handleGPUResources = ApplicationProperties::HandleGPUResources::Invalidate;
|
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-graphicsto log the graphics API calls
In |
|
||||
|
|||||
Values |
|
||||
|
# 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.
In |
|
||||
|
|||||
Values |
|
||||
|
# 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
In |
|
||||
|
|||||
Values |
|
||||
|
# 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.
In |
|
||||
|
|||||
Values |
|
||||
|
# Enables the logging of the graphics-related properties.
LogSurfaceInformation = 1
|
||||
|
// Enables the logging of the graphics-related properties.
configuration.propertyOutputEnabled = 1;
|
QNX system logger (slogger2)¶
On QNX you can use the QNX system logger (slogger2) to write log messages. When you redirect log messages to slogger2, your Kanzi application continues writing the log messages to the default logger.
A Kanzi application does not use the default slogger2 buffer, which allows you to use slog2_set_default_buffer. Kanzi provides slogger2 that supports logging to only one slogger2 buffer. When slogger2 stops logging, Kanzi calls slog2_reset. To change this behavior, see: Cleaning up after slogger2.
Keep in mind that slogger2 initializes after Kanzi reads the configuration for your Kanzi application. For this reason the slogger2 logs do not contain the log messages before that time.
To use slogger2, you can either:
Configure slogger2 in the
application.cfgorApplication::onConfigure.Provide a custom slogger2 buffer to the Kanzi logger. See customSlog2Buffer.
QnxEnableSlogger2¶
Before you can use slogger2 with your Kanzi application, you must enable it.
In |
|
||||
|
|||||
Values |
|
||||
|
# Enable logging to slogger2.
QnxEnableSlogger2 = true
|
||||
|
// Enable logging to slogger2.
configuration.slog2Config.enabled = true;
|
QnxSlogger2VerbosityLevel¶
You can set which log messages you want slogger2 to log. The Kanzi application configuration verbosity levels map to the slogger2 log verbosity levels.
In |
|
||||||||||||||||
|
|||||||||||||||||
Values |
|
||||||||||||||||
|
# Sets the slogger2 log level to SLOG2_INFO.
QnxSlogger2VerbosityLevel = Slog2Info
|
||||||||||||||||
|
// Sets the slogger2 log level to SLOG2_INFO.
configuration.slog2Config.verbosityLevel = Slog2VerbosityLevel::Slog2Info;
|
QnxSlogger2MaxRetries¶
On QNX versions 7.0.4 and newer you can limit the amount of times slogger2 retries to obtain a buffer.
When you set this limit and slogger2 reaches it, Kanzi drops the log message and increases the dropped message count. You can see the number of dropped messages in the slogger2 logs in the next non-dropped log entry of the variable code written before the log message.
In |
|
||
|
|||
Values |
|
||
|
# Set the retry limit to 10 retries.
QnxSlogger2MaxRetries = 10
|
||
|
// Set the retry limit to 10 retries.
configuration.slog2Config.maxRetries = 10;
|
pageCount¶
You can set the multiple of 4KB pages that the QNX logger acquires for the internal slogger2 buffer.
|
|||
Values |
|
||
|
// For example, when you set the slogger2 verbosity level to
// SLOG2_ERROR slogger2 writes to log less frequently
// (low rate logging), and by decreasing the page count
// you can increase the logging pace.
configuration.slog2Config.pageCount = 1;
|
customSlog2Buffer¶
Kanzi enables you to register a custom slogger2 buffer and pass it to a Kanzi application. Your Kanzi application then uses the buffer to write logs. For example, you can register a custom slogger2 buffer when you want to give the buffer a custom name or if you want to set any of the properties from the slog2_buffer_set_config_t structure passed to slog2_register. See QNX system logger (slogger2).
Graphics library¶
On the Windows operating system you can select whether you want to use OpenGL ES, OpenGL, or Vulkan 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:
--glesor--openglesto use OpenGL ES--glor--openglto use OpenGL--vkor--vulkanto use Vulkan--eglto use EGL--wglto use WGL--glxto use GLX
In |
|
||||
|
|||||
Values |
|
||||
|
# Sets the surface target for OpenGL rendering and WGL graphics context.
SurfaceClientAPI = gl
GraphicsContextAPI = wgl
|
||||
|
// Sets the surface target for OpenGL rendering and WGL graphics context.
configuration.defaultSurfaceProperties.clientAPI = SurfaceClientAPI::OpenGL;
configuration.defaultSurfaceProperties.contextAPI = GraphicsContextAPI::WGL;
|
GraphicsStatisticEnabled¶
You can enable the statistics layer for the Kanzi graphics library of your application. The statistics layer is always enabled in the debug mode, regardless of the configuration. The statistics layer shows the information about the Kanzi graphics objects in the Performance HUD. See Showing the performance measurement graphs in the Performance HUD.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Enables the statistics layer for the Kanzi graphics library.
GraphicsStatisticsEnabled = 1
|
||
|
// Enables the statistics layer for the Kanzi graphics library.
configuration.graphicsStatisticsEnabled = 1;
|
||
Command line example |
Enables the statistics layer for the Kanzi graphics library. --graphics-statistics
|
GraphicsValidationEnabled¶
You can enable the validation layer for the Kanzi graphics library of your application. The validation layer is always enabled in the debug mode, regardless of the configuration. Use the information in the validation layer to check whether your application correctly uses the graphics API. Kanzi shows validation errors in the default console.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Enables the validation layer for the Kanzi graphics library.
GraphicsValidationEnabled = 1
|
||
|
// Enables the validation layer for the Kanzi graphics library.
configuration.graphicsValidationEnabled = 1;
|
||
Command line example |
Enables the validation layer for the Kanzi graphics library. --graphics-validation
|
Surface properties¶
Surface properties control the properties of the hardware-accelerated graphics surface onto which Kanzi renders. They control the relation between image quality and rendering speed.
The surface properties that 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.
To get the platform-dependent default values of surface properties, call kzsSurfaceGetDefaultProperties().
Color format¶
You can set the sizes of the RGB color channels and the alpha channel in bits.
In |
|
||||||||
|
|||||||||
Values |
The default size of each channel is 8 bits. To let the platform choose the value, use |
||||||||
|
# Set the sizes of the color and alpha channels for a typical
# high-speed rendering application.
SurfaceBitsRed = 5
SurfaceBitsGreen = 6
SurfaceBitsBlue = 5
SurfaceBitsAlpha = 0
# Let the platform choose the sizes of the color and alpha channels.
SurfaceBitsRed = "unspecified"
SurfaceBitsGreen = "unspecified"
SurfaceBitsBlue = "unspecified"
SurfaceBitsAlpha = "unspecified"
|
||||||||
|
// Set the sizes of the color and alpha channels for a typical
// high-speed rendering application.
configuration.defaultSurfaceProperties.bitsColorR = 5;
configuration.defaultSurfaceProperties.bitsColorG = 6;
configuration.defaultSurfaceProperties.bitsColorB = 5;
configuration.defaultSurfaceProperties.bitsAlpha = 0;
To let the platform choose the color and alpha channel sizes:
|
SurfaceBitsStencil¶
You can set the size of the stencil buffer in bits.
In |
|
||
|
|||
Values |
|
||
|
# Set the size of the stencil buffer to one bit.
SurfaceBitsStencil = 1
# Let the platform choose the size of the stencil buffer.
SurfaceBitsStencil = "unspecified"
|
||
|
// Set the size of the stencil buffer to one bit.
configuration.defaultSurfaceProperties.bitsStencil = 1;
To let the platform choose the size of the stencil buffer:
|
SurfaceBitsDepthBuffer¶
You can set the size of the depth buffer in bits.
In |
|
||
|
|||
Values |
|
||
|
# Set the size of the depth buffer to 16 bits.
SurfaceBitsDepthBuffer = 16
# Let the platform choose the size of the depth buffer.
SurfaceBitsDepthBuffer = "unspecified"
|
||
|
// Set the size of the depth buffer to 16 bits.
configuration.defaultSurfaceProperties.bitsDepthBuffer = 16;
To let the platform choose the size of the depth buffer:
|
SurfaceBitsPadding¶
On QNX, you can set the size of the padding in bits to add to the color format of the Kanzi application window.
In |
|
||
|
|||
Values |
|
||
|
# Set the size of the padding to 2 bits.
SurfaceBitsPadding = 2
|
||
|
// Set the size of the padding to 2 bits.
configuration.defaultSurfaceProperties.bitsPadding = 2;
|
SurfaceColorSpace¶
You can enable the initialization of OpenGL for the hardware that displays your Kanzi application.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Set your application to use an unspecified color space.
SurfaceColorSpace = "standard"
|
||
|
// Set your application to use an unspecified color space.
configuration.defaultSurfaceProperties.colorSpace = "standard";
|
||
Command line example |
Set your application to use an unspecified color space. -surface-color-space=standard
|
See Color workflow.
SurfaceSamplesAntialiasing¶
You can set the number of surface samples to use for anti-aliasing.
In |
|
||
|
|||
Values |
|
||
|
# Set the number of anti-aliasing samples to 4.
SurfaceSamplesAntialiasing = 4
|
||
|
// Set the number of anti-aliasing samples to 4.
configuration.defaultSurfaceProperties.antiAliasing = 4;
|
SwapBehavior¶
You can set whether to swap or copy buffers during buffer swap.
In |
|
||
|
|||
Values |
|
||
|
# Copy buffers during buffer swap.
SwapBehavior = "copy"
|
||
|
// Copy buffers during buffer swap.
configuration.defaultSurfaceProperties.swapBehaviorCopy = SwapBehavior::Copy;
|
PresentMode¶
You can set the surface present mode. Not all platforms support this setting.
In |
|
||
|
|||
Values |
|
||
|
# Swap buffers at any time.
PresentMode = immediate
|
||
|
// Swap buffers at any time.
configuration.defaultSurfaceProperties.presentMode = kanzi::platform::PresentMode::Immediate;
|
EGLIMGContextPriority¶
You can create an EGL IMG context with a priority hint. By default, Kanzi lets the platform choose the priority.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Set the EGL IMG context priority to high.
EGLIMGContextPriority = "high"
# Let the platform choose the EGL IMG context priority.
EGLIMGContextPriority = "unspecified"
|
||
|
// Set the EGL IMG context priority to high.
configuration.defaultSurfaceProperties.priority = EGLIMGContextPriority::High;
To let the platform choose the EGL IMG context priority:
|
||
Command line example |
Set the EGL IMG context priority to high. -egl-img-context-priority=high
|
Application window position and size¶
You can set the position of your Kanzi 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.
To make the application window fixed size, resizable, fullscreen, or without borders, see WindowStyle.
To set the default display where the application window appears, see DefaultDisplayIndex.
In |
|
||||||||||
|
|||||||||||
Value |
|
||||||||||
|
# Sets 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
# Places the application window in the top-left corner of the device screen.
WindowX = 0
WindowY = 0
# Sets the window order to 0.
WindowOrder = 0
# Sets the window order to 0xff.
WindowOrder = 0xff
|
||||||||||
|
// Sets 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;
// Places the application window in the top-left corner of the device screen.
configuration.defaultWindowProperties.x = 0;
configuration.defaultWindowProperties.y = 0;
// Sets the window order to 0.
configuration.defaultWindowProperties.order = 0;
configuration.systemConfiguration[ConfigurationKeyDefaultWindowOrder] = "0";
// Sets the window order to 0xff.
configuration.defaultWindowProperties.order = 0xff;
configuration.systemConfiguration[ConfigurationKeyDefaultWindowOrder] = "0xff";
|
WindowClassName¶
You can set window class name for QNX and Win32 platforms.
In |
|
For the legacy graphics output.
For the new graphics output.
|
|
On the command line |
|
|
# Sets the window class name to "kanzi" for the legacy and new graphics outputs.
WindowClassName = "kanzi"
|
|
// Sets the window class name to "kanzi" for the legacy graphics output.
configuration.defaultWindowProperties.groupName = "kanzi";
// Sets the window class name for the new graphics output.
configuration.systemConfiguration[ConfigurationKeyDefaultWindowClassName] = "kanzi";
|
Command line example |
Sets the window class name to -window-class-name="kanzi"
|
Graphics card selection¶
DeviceIdentifier¶
On the platforms that use the GBM windowing system, you can set which graphics card you want your Kanzi application to use.
In |
|
||
|
|||
Value |
|
||
|
# Sets Kanzi to use the graphics card at /dev/dri/card1.
DeviceIdentifier = /dev/dri/card1
|
||
|
// Sets Kanzi to use the graphics card at /dev/dri/card1.
configuration.defaultDesktopProperties.deviceIdentifier = "/dev/dri/card1";
|
Preferred Vulkan GPU¶
You can set the GPU type to favor when the Kanzi Vulkan backend selects a device to use, where more than one GPU is available. By default Kanzi uses the first enumerated GPU.
In |
|
||
|
|||
Values |
|
||
|
# Prefer integrated GPU.
PreferredGPU = integrated
|
||
|
// Prefer integrated GPU.
configuration.preferredGPU = gfx::GpuSelectionType::Integrated;
|
QNX context type selection¶
On QNX, you can set the context type that you want your Kanzi application to use. In application.cfg and on the command line you can set only one context type. To set more than one context type, set it in the Application::onConfigure.
In |
|
||
|
|||
On the command line |
|
||
Value |
|
||
|
# Sets Kanzi to use the SCREEN_DISPLAY_MANAGER_CONTEXT context type.
QnxContextType = SCREEN_DISPLAY_MANAGER_CONTEXT
|
||
|
// Sets Kanzi to use the SCREEN_WINDOW_MANAGER_CONTEXT and SCREEN_INPUT_PROVIDER_CONTEXT context types.
configuration.defaultDesktopProperties.contextFlags = SCREEN_WINDOW_MANAGER_CONTEXT | SCREEN_INPUT_PROVIDER_CONTEXT;
|
||
Command line example |
Sets Kanzi to use the SCREEN_DISPLAY_MANAGER_CONTEXT context type. -qnx-context-type=SCREEN_DISPLAY_MANAGER_CONTEXT
|
Application window configuration¶
WindowStyle¶
You can set the style of your Kanzi application window. 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.
In |
|
||
|
|||
Value |
|
||
|
# 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;
|
DefaultDisplayIndex¶
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.
To make the application window fullscreen, see WindowStyle.
You can use this configuration option only on platforms where Kanzi owns the output window. This is not the case on Android. On Android, to launch your Android Activity on a particular display set the intent option with setLaunchDisplayId(id) or use adb with the --display argument. See https://source.android.com/docs/core/display/multi_display/activity-launch.
In |
|
||
|
|||
Value |
|
||
|
# Sets the second display as the default display for the full-screen application window.
DefaultDisplayIndex = 1
|
||
|
// Sets the second display as the default display for the full-screen application window.
configuration.defaultWindowProperties.defaultDisplayIndex = 1;
|
WindowBufferCount¶
If the windowing system of your target device supports setting the number of window buffers, you can set the number of native window buffers that your Kanzi application window uses. For example, Renesas window manager and QNX Screen support the setting of the number of window buffers.
In |
|
||
|
|||
Values |
|
||
|
# Set the number of native window buffers used by the Kanzi application window to 3.
WindowBufferCount = 3
|
||
|
// Set the number of native window buffers used by the Kanzi application window to 3.
configuration.defaultWindowProperties.bufferCount = 3;
|
QnxWindowBufferCount¶
Sets the number of native window buffers that your Kanzi application window uses on QNX platform. To ensure compatibility, if you do not set this configuration option explicitly, Kanzi uses the value from the WindowBufferCount configuration option.
In |
|
||
|
|||
Values |
|
||
|
# Set the number of native window buffers used by the Kanzi application window to 3.
QnxWindowBufferCount = 3
|
||
|
// Set the number of native window buffers used by the Kanzi application window to 3.
configuration.systemConfiguration[ConfigurationKeyQnxWindowBufferCount] = 3;
|
QnxStreamBufferCount¶
Sets the number of native stream buffers that your Kanzi application uses on QNX platform.
In |
|
||
|
|||
Values |
|
||
|
# Set the number of native stream buffers used by the Kanzi application to 3.
QnxStreamBufferCount = 3
|
||
|
// Set the number of native stream buffers used by the Kanzi application to 3.
configuration.systemConfiguration[ConfigurationKeyQnxStreamBufferCount] = 3;
|
GroupName¶
On platforms with windowing systems that use the window group name, such as QNX, you can set the group name for the application window group. When you run multiple Kanzi applications, in each Kanzi application set a unique name for the window group.
|
|||
Values |
|
||
|
// Set the Kanzi application window group name to Cluster.
configuration.defaultWindowProperties.groupName = "Cluster";
|
QnxPipelineID¶
You can set the QNX Screen pipeline ID for your Kanzi application window. A graphics pipeline ID is an identifier that refers to the hardware layering that is specific to your target device.
When you set the pipeline ID, your Kanzi application sets that ID using the underlying system functions. By default a Kanzi application does not set the pipeline ID.
If you set the pipeline ID, make sure that the pipeline order of your target device and the z-ordering of the application windows make sense together. You can set the z-order of a Kanzi application window using the WindowOrder setting. See Application window position and size.
In |
|
||
On the command line |
|
||
Values |
|
||
|
# Sets the QNX Screen pipeline ID to 1.
QnxPipelineID = 1
|
||
Command line example |
Sets the QNX Screen pipeline ID to 1. -qnx-pipeline-id=1
|
QnxUsageFlags¶
For a Kanzi application window you can programmatically set the usage flags for the QNX Screen property. Screen usage flags enable you to constrain the allocated QNX window buffers.
m_applicationProperties.defaultWindowProperties.usageFlags = usageFlags;
|
|||
Values |
|
||
|
// To use the OpenGL ES 3.X to render the QNX window buffer.
m_applicationProperties.defaultWindowProperties.usageFlags = SCREEN_USAGE_OPENGL_ES3;
|
EGLGraphicsFormatID¶
You can set the EGL graphics format ID for your Kanzi application. EGL graphics format ID is an identifier that refers to an EGL configuration for a Kanzi application that runs on EGL-supported platforms. Use the command line to list EGL configurations available for your Kanzi application.
Keep in mind that when you set the EGL graphics format ID, you override the EGL graphics format settings.
You can set the EGL format ID for these EGL graphics outputs:
Android WS
Emscripten
Wayland
X11
In |
|
||
On the command line |
|
||
Values |
|
||
|
# Sets the EGL graphics format ID to 1.
EGLGraphicsFormatID = 1
|
||
Command line example |
Sets the EGL graphics format ID to 1. -egl-graphics-format-id=1
Lists EGL configurations available for the application. -enum-egl-configs
|
EGLContextClientVersion¶
You can set the EGL context client version for these EGL graphics outputs:
Android WS
Emscripten
Wayland
QNX
X11
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Sets Kanzi to use ES2 context client version.
EGLContextClientVersion = es2
|
||
|
// Sets Kanzi to use ES2 context client version.
configuration.systemConfiguration[ConfigurationKeyEGLContextClientVersion] = "es2";
|
||
Command line example |
Sets Kanzi to use ES2 context client version. -egl-context-client-version=es2
|
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.
A Kanzi application handles input by default. To disable input handling in your application, override the Application::setScreenOverride() function with an empty implementation. See Disabling input handling.
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 |
|
||
|
|||
Values |
|
||
|
# Rotate a touch screen sized 1280x720 pixels by 180 degrees.
InputTransform = -1, 0, 0, 0, -1, 0, 1280, 720, 1
|
||
|
// Rotate a touch screen sized 1280x720 pixels by 180 degrees.
configuration.defaultEventSourceProperties.transformation = Matrix3x3::createTranslation(1280.0f, 720.0f) * 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.
In |
|
||
|
|||
Values |
|
||
|
# Translate pointer events to touch events.
InputTranslation = pointertotouch
|
||
|
// Translate pointer events to touch events.
configuration.defaultEventSourceProperties.translation = TranslatePointerToTouch;
|
InputDiscardPointer¶
You can set whether the application reacts to the pointer of the device.
In |
|
||||||
|
|||||||
Values |
|
||||||
|
# Ignore pointer input.
InputDiscardPointer = 1
|
||||||
|
// Ignore pointer input.
configuration.defaultEventSourceProperties.discardPointerEvents = 1;
|
InputDiscardTouch¶
You can set whether the application reacts to touch input.
In |
|
||||||
|
|||||||
Values |
|
||||||
|
# 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.
In |
|
||
|
|||
Values |
|
||
|
# 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";
|
Wayland configuration¶
When you use Kanzi on Wayland, you can configure Wayland-specific parameters.
Wayland shell¶
You can set which Wayland shell Kanzi uses.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Sets Kanzi to use the IVI shell.
WaylandShell = ivi
|
||
|
// Sets Kanzi to use the IVI shell.
configuration.systemConfiguration[ConfigurationKeyWaylandShell] = "ivi";
|
||
Command line example |
Sets Kanzi to use the IVI shell. -wayland-shell=ivi
|
Wayland input mode¶
If you do not want to wait for the pointer and touch frame() events, you can set Kanzi to process input events immediately.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Enable immediate input mode.
WaylandInputMode = immediate
|
||
|
// Enable immediate input mode.
configuration.systemConfiguration[ConfigurationKeyWaylandInputMode] = "immediate";
|
||
Command line example |
Enable immediate input mode. -wayland-input-mode=immediate
|
Wayland IVI surface ID¶
When you use the Wayland IVI shell, you can set which IVI surface ID Kanzi uses.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Sets IVI surface ID to 4000.
WaylandIviSurfaceId = 4000
|
||
|
// Sets IVI surface ID to 4000.
configuration.systemConfiguration[ConfigurationKeyWaylandIviSurfaceId] = 4000;
|
||
Command line example |
Sets IVI surface ID to 4000. -wayland-ivi-surface-id=4000
|
Wayland IVI extension configuration¶
When you use COVESA IVI extension and have Kanzi built with IVI extension support, you can control Kanzi by setting various IVI parameters.
Wayland IVI layer ID¶
Kanzi requires a dedicated IVI layer to display its content. You can set which IVI layer Kanzi uses.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Sets IVI layer ID to 4000.
WaylandIviLayerId = 4000
|
||
|
// Sets IVI layer ID to 4000.
configuration.systemConfiguration[ConfigurationKeyWaylandIviLayerId] = 4000;
|
||
Command line example |
Sets IVI layer ID to 4000. -wayland-ivi-layer-id=4000
|
Wayland IVI surface opacity¶
You can set the Kanzi IVI surface opacity.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Sets the IVI surface to be fully transparent.
WaylandIviSurfaceOpacity = 0
|
||
|
// Sets the IVI surface to be fully transparent.
configuration.systemConfiguration[ConfigurationKeyWaylandIviSurfaceOpacity] = 0;
|
||
Command line example |
Sets the IVI surface to be fully transparent. -wayland-ivi-surface-opacity=0
|
Wayland IVI layer opacity¶
You can set the Kanzi IVI layer opacity.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Sets the IVI layer to be fully transparent.
WaylandIviLayerOpacity = 0
|
||
|
// Sets the IVI layer to be fully transparent.
configuration.systemConfiguration[ConfigurationKeyWaylandIviLayerOpacity] = 0;
|
||
Command line example |
Sets the IVI layer to be fully transparent. -wayland-ivi-layer-opacity=0
|
Wayland IVI surface visibility¶
You can set the Kanzi IVI surface visibility.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Hides the Kanzi IVI surface.
WaylandIviSurfaceVisibility = 0
|
||
|
// Hides the Kanzi IVI surface.
configuration.systemConfiguration[ConfigurationKeyWaylandIviSurfaceVisibility] = 0;
|
||
Command line example |
Hides the Kanzi IVI surface. -wayland-ivi-surface-visibility=0
|
Wayland IVI layer visibility¶
You can set the Kanzi IVI layer visibility.
In |
|
||
|
|||
On the command line |
|
||
Values |
|
||
|
# Hides the Kanzi IVI layer.
WaylandIviLayerVisibility = 0
|
||
|
// Hides the Kanzi IVI layer.
configuration.systemConfiguration[ConfigurationKeyWaylandIviLayerVisibility] = 0;
|
||
Command line example |
Hides the Kanzi IVI layer. -wayland-ivi-layer-visibility=0
|
Image loading¶
Kanzi uses third-party image libraries, such as libpng and libjpeg, to support different image formats. To make your Kanzi application more secure, you can set limits for Kanzi to use when loading images using these libraries. For example, to prevent the loading of malicious files, you can limit the amount of memory to allocate for each object that Kanzi loads.
libjpeg¶
You can set the maximum amount of memory in bytes to allocate for each JPEG object that Kanzi loads using the libjpeg image library.
In |
|
||
|
|||
Values |
|
||
|
# Sets the libjpeg memory allocation limit to 2 MB (2,000,000 bytes).
LibJPEGMaxMemory = 2000000
|
||
|
// Sets the libjpeg memory allocation limit to 2 MB (2,000,000 bytes).
configuration.imageLoad.libJPEGMaxMemory = 2000000;
|
libpng¶
You can set the maximum number of ancillary chunks in a PNG datastream and the maximum amount of memory in bytes to allocate for a chunk that Kanzi loads using the libpng image library.
By default Kanzi uses these limits imposed by libpng:
Maximum total of 1000 sPLT, tEXt, iTXt, zTXt, and unknown ancillary chunks.
Maximum of 8 megabytes of memory to allocate for a chunk other than IDAT.
In |
|
||||
|
|||||
Values |
|
||||
|
# Sets the libpng limit for the number of ancillary chunks to 500.
LibPNGChunkCacheMax = 500
# Sets the libpng limit for the amount of memory that a chunk
# other than IDAT can occupy to 2 MB (2,000,000 bytes).
LibPNGChunkMallocMax = 2000000
|
||||
|
// Sets the libpng limit for the number of ancillary chunks to 500.
configuration.imageLoad.libPNGChunkCacheMax = 500;
// Sets the libpng limit for the amount of memory that a chunk
// other than IDAT can occupy to 2 MB (2,000,000 bytes).
configuration.imageLoad.libPNGChunkMallocMax = 2000000;
|
Shader binary cache¶
On performance-constrained platforms, shader compilations can considerably slow down the application startup and decrease runtime performance. You can use a shader binary cache primed with the set of shaders that your application requires. This way, your application does not have to compile shaders from source at runtime.
See Using binary shaders.
ShaderBinaryCacheDirectory¶
You can set the directory where you want your Kanzi application to cache shader binaries. At the time of caching, this directory must be writable. For production purposes, you can make the directory read-only. See ShaderBinaryCacheReadOnly.
To enable the caching of shader binaries, use the ShaderBinaryCacheEnabled setting.
In |
|
||
|
|||
Values |
|
||
|
# Sets the shader binary cache directory to /tmp/shader-cache/.
ShaderBinaryCacheDirectory = "/tmp/shader-cache/"
|
||
|
// Sets the shader binary cache directory to /tmp/shader-cache/.
configuration.shaderBinaryCacheDirectory = "/tmp/shader-cache/";
|
ShaderBinaryCacheEnabled¶
You can set your application to cache shader binaries. Use this to optimize Kanzi application performance on platforms where offline shader compilation tools are not available.
The caching of shader binaries requires that Kanzi Studio exports the source code of the shaders to the kzb file. In Kanzi Studio, in the Project > Properties, make sure that the Export Shader Source Code property is enabled. This is the default value.
In |
|
||||
|
|||||
Values |
|
||||
|
# Enables the caching of shader binaries.
ShaderBinaryCacheEnabled = true
|
||||
|
// Enables the caching of shader binaries.
configuration.shaderBinaryCacheEnabled = true;
|
ShaderBinaryCacheCollisionCheck¶
By default, Kanzi stores in the filename of a cached shader binary only a hash of the shader source code. Kanzi then compares that hash to a hash value derived from the requested shader source. Hash collisions, which are rare but possible, result in the use of the wrong shader.
To guard against hash collisions, you can set your application to store the shader source code and perform a full string comparison to make sure that the shaders are identical. If two shaders produce the same hash value, the application logs a warning.
To save disk space and optimize performance, enable the hash collision checks only during development.
In |
|
||||
|
|||||
Values |
|
||||
|
# Enables checking for hash collisions in cached shaders.
ShaderBinaryCacheCollisionCheck = true
|
||||
|
// Enables checking for hash collisions in cached shaders.
configuration.shaderBinaryCacheCollisionCheck = true;
|
ShaderBinaryCacheReadOnly¶
By default, Kanzi can write to the shader binary cache. When your application is ready for production, you can make the shader binary cache read-only.
In |
|
||||
|
|||||
Values |
|
||||
|
# Makes the shader binary cache read-only.
ShaderBinaryCacheReadOnly = true
|
||||
|
// Makes the shader binary cache read-only.
configuration.ShaderBinaryCacheReadOnly = true;
|