C

Managing Resources

This topic describes how Qt Quick Ultralite applications make use of image resources.

Font resources are not added through the resource system. For more information about font handling, see Text Rendering and Fonts.

See also topic on Image Caching.

Summary

To use resources in a Qt Quick Ultralite application, you must declare them using the CMake API.

The resource compiler (qulrcc) uses the resource declarations to prepare the contents for inclusion. It may perform optimizations on the raw resource data. For example, image optimization can result in lowering color depth, replacing with alphamap, removing outline transparent areas, and swizzling.

Adding files to the resource system

Use the qul_add_resource CMake function to add resources to a Qt Quick Ultralite application.

qul_add_resource(myapp FILES ui/spinner.png background.png)

The function adds the files into to a virtual resource filesystem. Resources in the filesystem are referenced through resource URIs with the optional "qrc:" scheme.

qrc:/
  |-- background.png
  |-- ui/
       |-- spinner.png

In the above example, qrc:/ui/spinner.png is a resource URI for the resource data based on the ui/spinner.png file from the source directory. It can be displayed by using its URI as source in an Image:

Image {
    source: "qrc:/ui/spinner.png"
}

When using relative paths in resource URIs, the paths are relative to the root of the virtual resource filesystem. The scheme of the URI can be omited. The following URIs all refer to ui/spinner.png:

  • ui/spinner.png
  • /ui/spinner.png
  • qrc:ui/spinner.png
  • qrc:/ui/spinner.png
  • qrc:///ui/spinner.png

Resource properties

Optionally, use the set_source_files_properties CMake function to set resource properties. It must be done before calling qul_add_resource.

set_source_files_properties(filename.png PROPERTIES QUL_RESOURCE_COMPRESSION ON)

Image resources support a number of resource properties that control how the image is stored on the device, or can trigger different optimizations. See CMake Source File Properties for the full list.

In the following example, the large background.png is stored in a compresed format by setting QUL_RESOURCE_COMPRESSION, while spinner.png is tagged with QUL_RESOURCE_OPTIMIZE_FOR_ROTATION to optimize it for runtime rotation:

set_source_files_properties(spinner.png PROPERTIES QUL_RESOURCE_OPTIMIZE_FOR_ROTATION ON)
set_source_files_properties(background.png PROPERTIES QUL_RESOURCE_COMPRESSION ON)
qul_add_resource(myapp FILES spinner.png background.png)
Image {
    source: "qrc:/background.png"

    Image {
        anchors.centerIn: parent
        source: "qrc:/spinner.png"
        transform: Rotation {
            NumberAnimation on angle { from: 0; to: 360; running: true; loops: Animation.Infinite }
        }
    }
}

Resource placement in memory

By default a resource is placed in a reserved memory section named QulResourceData. Resources can be placed in a different storage section by setting the QUL_RESOURCE_STORAGE_SECTION property.

In the following example, three images are stored in a memory section named Arrows.

set(ARROWS
    images/arrow-0.png
    images/arrow-45.png
    images/arrow-90.png
)

set_source_files_properties(${ARROWS} PROPERTIES QUL_RESOURCE_STORAGE_SECTION "Arrows")
qul_add_resource(app FILES ${ARROWS})

The section name can be freely chosen as long as a section with the same name is defined in the linker script. The section start address needs to be aligned to the largest alignment requirement among resources within the same section.

Arrows :
{
    . = ALIGN(4);
    *(Arrows)
} > QSPI_FLASH

OTA resources update

If the user wants to do an over-the-air (OTA) update of some resources, these resources should be placed in a specific memory section (for example OTAResourceSection) as shown above in Resource placement in memory.

Once the user has updated the images that are part of the OTA update on the host, it is possible to regenerate the binary content of the OTAResourceSection for a given target application.

Such binary generation is performed by the resource compiler and can be invoked via CMake as follows:

cmake --build . --target <application>_resource_binaries

without the need of recompiling the whole application. The resource binaries are named qul_resources_<section_name>.bin (for example qul_resources_OTAResourceSection.bin) and can be found in the target application build folder.

Since some of the images might either be cached (OnDemand) or preloaded at startup (OnStartup), the Qt Quick Ultralite application must be restarted for the images part of the OTA update to be effectively used by the application.

Notes

  • Apart from generating new binary data, Qt Quick Ultralite does not offer any direct mechanism for rewriting the data to Flash memory. An application specific solution will need to be implemented.
  • The resource binary content is in Little-Endian format.
  • Filenames need to match with the ones that have been used in the QML application originally. Otherwise the resource lookup will fail.
  • To avoid overwriting other memory areas, the section part of an OTA update should be placed last in Flash.
  • Please note that flash memory needs to be erased and rewritten on a block by block basis. If the binary data does not start and end on exact block boundaries, it might be necessary to first read the old data for the areas that would otherwise get erased. Make sure to take this into consideration if the flashing tool or library you are using does not handle it automatically.

Available under certain Qt licenses.
Find out more.