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 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.

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.

cmake examples/imagedecoder -DCMAKE_PREFIX_PATH=<Path/To/Qt> -DQUL_PLATFORM=Qt -DQul_ROOT=${QulROOT}

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.

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 by applying the filesystemSupport selector in CMakeLists.txt.

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.

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.