C

Qt Quick Ultralite imagedecoder Example

Demonstrates how to load custom image formats.

Overview

This example shows how implement and register a custom image decoder to the QML engine.

The example consists of a simple screen (imagedecoder.qml) that shows different images. These images are not processed by the Qt Quick Ultralite resource compiler and kept as is. Two of the images are copied unchanged into the resource system, while the other two are read from a file system without having to be declared at all.

Warning: Loading assets from external storage has potential security threats.

Target platforms

Note: The STM32H750B Discovery kit, RH850/D1M1A Evaluation Board and Infineon TRAVEO T2G CYT4DN do not have an SD card slot. The example is modified to exclude the use of images on filesystem. See example/imagedecoder/rootqml/+noFilesystemSupport/imagedecoder.qml and example/imagedecoder/qmlproject_stm32h750b.qmlproject, example/imagedecoder/imagedecoder_traveo_t2g.qmlproject respectively.

Note: Due to a limitation of the Graphics Driver, currently the only supported subsampling mode for source JPEG images is YUV420. See Sample application user guide for JPEG decode driver TRAVEO T2G cluster series User Manual for more information. To convert source images to the YUV420 subsampling format, you can use ImageMagick Convert tool: convert input.jpg -sampling-factor 4:2:0 output.jpg.

Note: For Infineon TRAVEO T2G CYT4DN, set the mandatory CMake variable TVII_JPEG_DRIVER_DIR. It should point to the root folder of the JPEG decode driver SDK.

On the RH850 platform, add the following compile definitions to configure the JPEG driver:

USE_OUTPUT_SPLIT_MODE
Configures the Renesas JCUA hardware in division mode where the decoding is performed in chunks. This definition can be skipped if normal mode is to be used where complete image is decoded at once.
DECODE_BUFFER_PIXEL_LINES
If USE_OUTPUT_SPLIT_MODE is enabled, DECODE_BUFFER_PIXEL_LINES sets the number of output buffer pixel lines which will be processed in one iteration. This value must be multiple of 16.

The default value of DECODE_BUFFER_PIXEL_LINES is 16.
CHROMA_SUBSAMPLING
Sets the chroma-subsampling format of the images in use. The possible values are as follows:
1. R_JCUA_JPEG_FORMAT_YCBCR420
2. R_JCUA_JPEG_FORMAT_YCBCR411
3. R_JCUA_JPEG_FORMAT_YCBCR422
4. R_JCUA_JPEG_FORMAT_YCBCR444
The default value of CHROMA_SUBSAMPLING is R_JCUA_JPEG_FORMAT_YCBCR420.

Note: Currently, the chroma-subsampling cannot be determined at runtime and has to be specified at compile time. All jpeg images used in the application must be saved with same chroma-subsampling.

Running the example on a device

After building the example, the images being loaded from the file system have to be copied to the root folder of a FAT32 formatted SD card:

basse-terre-guadeloupe.jpg
yosemite-national-park.jpg

This only applies to STM32F769I because this board comes with an SD card slot. On the STM32 platforms, the image decoder makes use of the accelerated hardware decoder for JPEG images.

Running the example on desktop

The desktop implementation uses Qt to decode the images. Hence the project requires a development Qt for building to provide the headers.

LinuxWindows

cmake examples/imagedecoder -DCMAKE_PREFIX_PATH=$HOME/Qt/6.2.4/gcc_64 -DQUL_PLATFORM=Qt -DQul_ROOT=${QUL_ROOT}

cmake examples\imagedecoder -DCMAKE_PREFIX_PATH=C:\Qt\6.2.4\msvc_2019 -DQUL_COMPILER_NAME=msvc -DQUL_PLATFORM=Qt -DQul_ROOT=%QUL_ROOT%

To avoid linking issues with the Qt version the platform backend is linked against, this has to be the same version. For custom built platforms use the same Qt that was used to build the desktop platform backend. For prebuilt platform libraries it has to be Qt 6.2.4.

Note: When using MinGW, use gnu as the compiler name and C:\Qt\6.2.4\mingw_64 as CMAKE_PREFIX_PATH.

Project structure

On platforms with an SD card slot, the example includes FatFS file system API implementations, and a Posix implementation in the desktop folder for Windows and Linux hosts. The root qml file imagedecoder.qml for such platforms is selected when no file selectors are applied.

For the platforms which do not have an SD card slot, the example is slightly modified. The root qml file imagedecoder.qml is selected by applying the noFilesystemSupport selector in CMakeLists.txt or using the --selector command-line argument when exporting the project with qmlprojectexporter.

The main functions in os/baremetal and os/freertos will call a ConfigureBoard() function that has to be implemented for a board. This function has to setup the SD Card hardware, register the file system and the image decoder with Qt Quick Ultralite.

Implementations for these functions are available at board_config.cpp in sub-folders named after the platforms (desktop, stm, traveo_t2g).

Decoding images

In Qt Quick Ultralite it is possible to register image decoders for further image formats. When Qt Quick Ultralite encounters an image that does not have the built-in asset format, all registered decoders are checked if one of them can decode the image. There is no special syntax for this, the image source can be from flash or a file system as usual.

Column {
    Text {
        anchors.horizontalCenter: parent.horizontalCenter
        font.pixelSize: 12
        text: " Jpeg Images from flash"
    }

    Image {
        width: 240
        height: 144
        fillMode: Image.PreserveAspectFit
        //Below images are stored as assets in flash memory
        source: leftImageToggle? "grand-canyon-arizona.jpg" : "sequoia-national-park.jpg"
    }
}

Column {
    Text {
        anchors.horizontalCenter: parent.horizontalCenter
        font.pixelSize: 12
        text: "Jpeg images from filesystem"
    }

    Image {
        width: 240
        height: 144
        fillMode: Image.PreserveAspectFit
        //Below images must be present on SD Card root folder for embedded platforms.
        source: rightImageToggle?"file://basse-terre-guadeloupe.jpg" : "file://yosemite-national-park.jpg"
    }
}

It is possible to include the unchanged image data in the application binary by declaring it as a resource. When loading the image data from a file system, using the "file://" protocol, it does not need to be declared ahead of time.

ImageFiles {
    files: [
        "grand-canyon-arizona.jpg",
        "sequoia-national-park.jpg"
    ]
    MCU.resourceKeepRawData: true
}

To include the raw image data as resource, you need to enable the MCU.resourceKeepRawData property.

Files:

Images:

Available under certain Qt licenses.
Find out more.