The OpenSTLinux distribution enables the generation of example images based on the QT framework (st-example-image-qt and, for ecosystem release ≥ v2.1.0 , st-example-image-qtwayland) for demonstration purposes, not for developing products.
This article provides information on how to create the SDK to build QT applications based on the above image examples .
1. Prerequisites[edit source]
Must be able to rebuild an OpenSTLinux image
2. OpenSTLinux QT images and SDK[edit source]
OpenSTLinux distribution provides two examples of images based on the QT framework:
- st-example-image-qt (requires 'openstlinux-eglfs' distro): only one QT application can access the screen. It is displayed in full-screen mode. This provides the best performance as the QT application accesses the screen without the overhead of a window manager.
- st-example-image-qtwayland (requires 'openstlinux-weston' distro and ecosystem release ≥ v2.1.0 ): thanks to weston window management, QT applications are displayed in independent windows and can coexist on the same screen with other non-QT applications. The window management adds extra overhead, decreasing the overall performance of the QT application. If the QT application must run in full-screen mode, choose the previous image.
To build the images and the associated SDK, start installing the OpenSTLinux distribution with the procedure described in Installing the OpenSTLinux distribution chapter ("STM32MP1 Distribution Package" article).
2.1. QT image and SDK with EGLFS[edit source]
The QT image and SDK use QT back-end to run single QT applications in full-screen mode.
Initialize the OpenEmbedded build environment for the openstlinux-eglfs distro:
DISTRO=openstlinux-eglfs MACHINE=stm32mp1 source layers/meta-st/scripts/envsetup.sh
Read and accept EULA. Refer to Initializing the OpenEmbedded build environment for more details.
Build the image and the SDK:
bitbake st-example-image-qt bitbake st-example-image-qt -c populate_sdk
Refer to Generating your own Starter and Developer Packages and How to create an SDK for OpenSTLinux distribution for more details.
Note: the legacy command bitbake meta-toolchain-qt5 is not recommended because the resulting SDK might miss some target packages.
The image can be flashed on the target board as in Flashing the built image.
The generated SDK is available in the tmp-glibc/deploy/sdk/ folder. It can be installed as described in Installing the SDK chapter ("STM32MP1 Developer Package" article), using the following command:
./tmp-glibc/deploy/sdk/st-example-image-qt-openstlinux-eglfs-stm32mp1-x86_64-toolchain-4.0.4-openstlinux-5.15-yocto-kirkstone-mp1-v22.11.23.sh -y -d <working directory absolute path>/Developer-Package/SDK
2.1.1. Selecting the display resolution and size in EGLFS[edit source]
When using a display that accepts multiple resolutions, the preferred resolution can be specified by editing the board file /usr/share/qt5/cursor.json. For example, for an HDMI display, change the line:
{ "name": "HDMI1", "mode": "1280x720" },
and enter one of the valid resolutions reported by the command:
modetest
If the current display resolution is higher than the resolution requested by the QT application, QT expands the application to run it in full screen. This can produce blurred images on the display and can impact the system performance.
The QT framework can be configured to use only one part of the overall display. For example, to use only an area of 400x300 pixels, add:
{ "name": "HDMI1", "mode": "1280x720", "size": "400x300" },
2.2. QT image and SDK with weston/wayland[edit source]
The QT image and SDK use QTwayland back-end to run QT applications in independent windows managed by weston. This requires ecosystem release ≥ v2.1.0 .
Initialize the OpenEmbedded build environment for the openstlinux-weston distro:
DISTRO=openstlinux-weston MACHINE=stm32mp1 source layers/meta-st/scripts/envsetup.sh
Read and accept EULA. Refer to Initializing the OpenEmbedded build environment for further details.
Build the image and the SDK:
bitbake st-example-image-qtwayland bitbake st-example-image-qtwayland -c populate_sdk
Refer to Generating your own Starter and Developer Packages and How to create an SDK for OpenSTLinux distribution for further details.
Note: the legacy command bitbake meta-toolchain-qt5 is not recommended because the resulting SDK might miss some target packages.
The image can be flashed on the target board as in Flashing the built image.
The generated SDK is available in the tmp-glibc/deploy/sdk/ folder. It can be installed as described in Installing the SDK chapter ("STM32MP1 Developer Package" article), using the following command:
./tmp-glibc/deploy/sdk/st-example-image-qtwayland-openstlinux-weston-stm32mp1-x86_64-toolchain-4.0.4-openstlinux-5.15-yocto-kirkstone-mp1-v22.11.23.sh -y -d <working directory absolute path>/Developer-Package/SDK
3. Building a QT application[edit source]
Pre-existing QT applications are usually deployed as "project" with one or more .pro file. In such case, QT application can be easily build by qmake command.
Open the folder that contains the application, enable the QT SDK and compile the application:
cd <path_of_app> . <install_path_sdk>/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi qmake && make
If the application does not provide the .pro file, it can be created through the command qmake -project. Check qmake documentation for more information.
Note that, CMake tool begins to replace qmake tool and is being used more and more in different projects.
4. Hints to get better performance on embedded platforms[edit source]
Embedded platforms don't share the same high performance as general-purpose personal computers (PC). QT applications that run correctly on a PC might require some adaptation and optimization to run on an embedded platform. Some examples and suggestion to develop or port a QT application to an embedded platform are given below:
- Designers must understand the performance characteristics of their designs, and avoid creating solutions that end up being very expensive to render.
- Use preferably Qt Quick instead of Qt Widget to ease designers in providing not only assets, layouts, etc., but to actually develop the relevant QML code, either by hand or by using the Designer integrated into Qt Creator. The resulting code is still code, and therefore must be reviewed.
- Avoid having artwork that requires resizing at runtime (for instance, a full-HD background image, used on a 800x480 display). Instead, prepare all the artwork in the correct sizes. Avoid multiplying opacity level between elements, or big transparent areas in artwork.
- Avoid overdrawing. Sometimes designs stack a lot alpha-blended visual elements on top of each other. This must be avoided as much as possible. When using OpenGL, QtQuick (directly, by setting QSG_VISUALIZE=overdraw, or through GammaRay) it can visualize the amount of overdraw in a given scene.
- Avoid too much clipping. Same as, (ab)using clipping can reduce performance drastically. When disabling the depth/stencil buffers, only screen-aligned clipping is possible (because scissoring is used instead). The main problem with clipping is that it might get used inside reusable UI components such as, buttons, dials, etc. As a consequence, clipping might be all on the screen at the same time. (QSG_VISUALIZE=clip).
These practical examples are useful for end-users with basic hardware knowledge and for any QT applications. Giuseppe D'ANGELO from KDAB, explains this in this very good presentation.