qtquick3d-cmake-macros.qdoc

Go to the documentation of this file.

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qt-add-materials.html
\ingroup cmake-commands-qtquick3d
 
\title qt_add_materials
\keyword qt6_add_materials
\deprecated
 
\summary {Generates shaders from files, adding them as Qt resources.}
 
\preliminarycmakecommand
 
The command is defined in the \c Quick3D component of the \c Qt6 package, which can
be loaded like this:
 
\badcode
find_package(Qt6 REQUIRED COMPONENTS Quick3D)
\endcode
 
\cmakecommandsince 6.2
 
\section1 Synopsis
 
\badcode
qt_add_materials(target resource_name
                 [PREFIX prefix]
                 FILES file1.qml, file2.qml ...)
\endcode
 
\versionlessCMakeCommandsNote qt6_add_materials()
 
\section1 Description
 
Use the command to pre-generate the material shaders used in a \l{Qt Quick 3D} scene
at compile time, for a certain \c target.
 
Use \c FILES to list the QML files that are part of the project. The command will call
the \l{Shadergen Tool} at build time to extract and generate material shaders,
making them available in the Qt resource system. \l{Qt Quick 3D} will automatically
load these at runtime.
 
Using \c RESOURCES is currently not supported.
 
\section1 Example
 
The following autogenerates the lightprobe map at build time and
includes it in the executable under \c{:/maps/OpenfootageNET_garage-1024.ktx}:
 
\badcode
qt6_add_materials(offlineshaders "shaders"
    PREFIX
        "/"
    FILES
        MaterialRed.qml
        MaterialRedExtended.qml
        main.qml
)
\endcode
 
\section1 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 \l{Shadergen Tool}
documentation on further details.
 
When adding multiple resources, \c 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.
 
\sa {Shadergen Tool}, {Qt Quick 3D - Offline Shaders Example}
*/
 
/*!
\page qt-add-lightprobe-images.html
\ingroup cmake-commands-qtquick3d
 
\title qt_add_lightprobe_images
\keyword qt6_add_lightprobe_images
 
\summary {Bakes HDRI map files to KTX files, adding them as Qt resouces.}
 
\preliminarycmakecommand
 
The command is defined in the \c Quick3D component of the \c Qt6 package, which can
be loaded like this:
 
\badcode
find_package(Qt6 REQUIRED COMPONENTS Quick3D)
\endcode
 
\cmakecommandsince 6.2
 
\section1 Synopsis
 
\badcode
qt_add_lightprobe_images(target resource_name
                    [PREFIX prefix]
                    [BASE base]
                    FILES file1.hdr, file2.hdr ..
                    [OUTPUTS file1.ktx, file2.ktx ..]
)
\endcode
 
\versionlessCMakeCommandsNote qt6_add_lightprobe_images()
 
\section1 Description
 
Use the command to bake \c{.hdr} files listed under \c FILES
to \c{.ktx} files. The files will be included under in the binary
or library \c target.
 
\c FILES should list paths to local HDRI map files. Each file must have either
the suffix \c{.hdr}, or \c{.exr}. These files will be converted at build time
to \c .ktx files, using the \l{Balsam Asset Import Tool}.
 
By default, the \c .ktx files will show up in embedded Qt resources of
the target binary under the same base name and relative path. Use \c BASE
to remove a common directory from the relative paths at runtime. That is, if all
the file paths under \c FILES point to a common directory \c maps/, then you
can use \c{BASE maps/} to hide the directory in the Qt resource system. In a similar
vein, you can use \c PREFIX to add a common prefix directory in the Qt resource
system.
 
While \c BASE and \c PREFIX allow you to change the comon relative paths of
the \c .ktx files in the Qt resource system, \c OUTPUTS allow you to control
the full path of the \c .ktx files, including the file name. If you use \c OUTPUTS,
the number of paths have to match the number of paths to \c FILES.
 
 
\section1 Example
 
The following autogenerates the lightprobe map at build time and
includes it in the executable under \c{:/maps/OpenfootageNET_garage-1024.ktx}:
 
\badcode
qt_add_lightprobe_images(principledmaterial "ibl_assets"
    PREFIX
         "/"
    FILES
        "maps/OpenfootageNET_garage-1024.hdr"
)
\endcode
 
\section1 Caveats
 
When adding multiple resources, \c 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.
 
\sa{Pre-generating IBL cubemap}
*/