qt_add_materials

Generates shaders from files, adding them as Qt resources.

The command is defined in the Quick3D component of the Qt6 package, which can be loaded like this:

find_package(Qt6 REQUIRED COMPONENTS Quick3D)

This command was introduced in Qt 6.2.

Synopsis

qt_add_materials(target resource_name
                 [PREFIX prefix]
                 FILES file1.qml, file2.qml ...)

If versionless commands are disabled, use qt6_add_materials() instead. It supports the same set of arguments as this command.

Description

Use the command to pre-generate the material shaders used in a Qt Quick 3D scene at compile time, for a certain target.

Use FILES to list the QML files that are part of the project. The command will call the Shadergen Tool at build time to extract and generate material shaders, making them available in the Qt resource system. Qt Quick 3D will automatically load these at runtime.

Using RESOURCES is currently not supported.

Example

The following autogenerates the lightprobe map at build time and includes it in the executable under :/maps/OpenfootageNET_garage-1024.ktx:

qt6_add_materials(offlineshaders "shaders"
    PREFIX
        "/"
    FILES
        MaterialRed.qml
        MaterialRedExtended.qml
        main.qml
)

Caveats

Shadergen uses a heuristic to determine the shaders it generates, which might not always be the ones that are actually used at runtime. See the Shadergen Tool documentation on further details.

When adding multiple resources, resource_name must be unique across all resources linked into the final target. This especially affects static builds. There, the same resource name in different static libraries conflict in the consuming target.