着色器工具

Shadergen Tool

着色器工具

The shadergen tool is a command line application that is part of Qt Quick 3D's asset conditioning pipeline. It can be enable per project or run manually from the command line. Pre-generating the material shaders can have a significant impact on the start-up time and/or avoid unwanted stalls at run-time, as the processes of creating a material shader at run-time can be costly.

shadergen工具是一个命令行应用程序，是Qt Quick 3D资产调节管道的一部分。它可以按项目启用，也可以从命令行手动运行。预生成材质着色器可能会对启动时间产生重大影响或避免在运行时出现不必要的停顿，因为在运行时创建材质着色器的过程可能成本高昂。

Note: This tool is experimental and under development, but most common use-cases should work already.

注意：这个工具是实验性的，正在开发中，但大多数常见的用例应该已经可以使用了。

One of the biggest obstacles for the offline shader generator is the amount of different materials that can be generated, not only based on the material properties themeself but also how the rest of the scene is set-up; for example, light count, light type, shadows, etc. all affect the generated shader(s). When we also take dynamic properties into account, the share amount of material shader permutations can very quickly make it unfeasible to generate them all at build-time. To limit the amount of shaders the tool needs to generate, the tool tries to only generate the shaders it think the application needs. The heuristics used in the tool might not always be able to detect which materials should be generate, this is espcecially true for properties that change at run-time. To verify that the material shaders were successfully, and correctly, generated, the tool should have generated a .qsbc file which can be inspected to verify that the content matches the material used by the application. It's also possible to verify that the material was loaded from the pre-built cache by setting the environment variable QT_RHI_SHADER_DEBUG=1 and looking at the debug output for mentions of the engine loading the pregenerated shader successfully.

​离线着色器生成器的最大障碍之一是可以生成的不同材质的数量，这不仅取决于材质本身的特性，还取决于场景其余部分的设置方式；例如，灯光数量、灯光类型、阴影等都会影响生成的着色器。当我们还考虑到动态特性时，材质着色器排列的共享量可能会很快使在构建时无法全部生成它们。为了限制该工具需要生成的着色器数量，该工具尝试仅生成它认为应用程序需要的着色器。该工具中使用的启发式方法可能并不总是能够检测出应该生成哪些材料，尤其是对于在运行时发生变化的属性。若要验证材质着色器是否已成功且正确地生成，该工具应已生成一个.qsbc文件，可以对该文件进行检查，以验证其内容是否与应用程序使用的材质匹配。还可以通过设置环境变量QT_RHI_SHADER_DEBUG=1并查看调试输出中是否提到引擎成功加载预生成着色器来验证材质是否已从预生成缓存加载。

Known limitations are:

已知的限制是：

• Scenes with more then one View3D.
• ​具有多个View3D的场景。
• Dynamically adding or removing lights are not supported when using generating materials.
• 使用生成材质时，不支持动态添加或删除灯光。
• The generated shaders are strictly tied to the Qt version used due to its dependency on the internals of the renderer. Compatibility of the generated shaders can therefore not be guaranteed between versions.
• 生成的着色器严格绑定到所使用的Qt版本，因为它依赖于渲染器的内部。因此，无法保证生成的着色器在不同版本之间的兼容性。

Usage

用法

To enable offline generation of material shaders in your project, add the following to your project file:

若要在项目中启用脱机生成材质着色器，请将以下内容添加到项目文件中：

CMake:

qt6_add_materials(offlineshaders "shaders"
    PREFIX
        "/"
    FILES
        ${qml_resource_files}
)

Alternatively the shadergen tool can be invoked manually from the command line, like this:

或者，shadergen工具可以从命令行手动调用，如下所示：

shadergen main.qml Material.qml

Normally the shadergen tool should be run from your application's project folder, but it's also possible to instruct the tool to change its current working directory through the -C argument.

通常，shadergen工具应该从应用程序的项目文件夹中运行，但也可以通过-C参数指示该工具更改其当前工作目录。

If no output path is provided then the tool will write the generated files to the current directory. The output path can be changed with the -o option.

如果没有提供输出路径，则该工具将把生成的文件写入当前目录。可以使用-o选项更改输出路径。

Note that for the tool to generate the expected materials it will need to know about the whole scene and not just the material(s), for example the number of lights in the scene does also affect how the materials get generated, so all relevant qml files should be added to the list of files the tool needs to process.

请注意，对于生成预期材质的工具，它需要了解整个场景，而不仅仅是材质，例如场景中的灯光数量也会影响材质的生成方式，因此所有相关的qml文件都应添加到工具需要处理的文件列表中。

Command line arguments

命令行参数

Short	Full	Description
-C <PATH>	–directory <PATH>	Changes the current directory to <PATH>. This argument is optional. 将当前目录更改为＜PATH＞。此参数是可选的。
-o <PATH>	–output-dir <PATH>	Sets the output path to <PATH>. This is the location where the files generated by the tool will be placed under. If no path is given the path is current directory. 将输出路径设置为＜path＞。这是工具生成的文件将放置在的位置。如果未给定路径，则路径为当前目录。
-r <NAME>	–resource-file <NAME>	Changes the name of the generated resource file to <NAME>. This argument is optional. 将生成的资源文件的名称更改为<name>。此参数是可选的。
-l <FILE>	–list-qsbc <FILE>	List the content of the qsbc file. 列出qsbc文件的内容。

Generated content

生成内容

The shadergen tools main output file is a .qsbc file. The .qsbc file contains a collection of .qsb files plus some meta-data about the various material shaders, like the unique property string for each material.

​shadergen工具的主输出文件是一个.qsbc文件。.qsbc文件包含.qsb文件的集合以及有关各种材质着色器的一些元数据，例如每个材质的唯一属性字符串。

The .qsbc file can be inspected by calling the shadergen tool with the -d argument:

可以通过使用-d参数调用shadergen工具来检查.qsbc文件：

shadergen -d qtappshaders.qsbc

Dynamic properties

动态属性

Since the tool is run at build-time it has limited ability to reason about which properties might change at run-time. Properties where a value is only changing within the properties range, for example the roughness value, will not have any affect on the generated material shader, but properties that are either on or off, e.g., setting an image map at run-time, would require a different type of material to be generated. It is therefore recommended that all variants of a material, which enables or disables features in the material, or the scene, are declared as individual components, this will help the tool to generated the correct material shaders.

由于该工具是在构建时运行的，因此它推理哪些属性可能在运行时更改的能力有限。值仅在属性范围内变化的特性（例如粗糙度值）不会对生成的材质着色器产生任何影响，但打开或关闭的属性（如在运行时设置图像贴图）将需要生成不同类型的材质。因此，建议将启用或禁用材质或场景中功能的材质的所有变体声明为单独的组件，这将有助于该工具生成正确的材质着色器。

The following example shows a contrived example of a material where we want to add a base color map to a material at run-time. Note that the component MaterialRedExtended is never used in the example, it's purely defined to help the shadergen tool generate the shaders needed to dynamically set the baseColorMap at run-time.

下面的示例显示了一个设计好的材质示例，其中我们希望在运行时向材质添加基本颜色贴图。请注意，该示例中从未使用组件MaterialRedExtended，它的定义纯粹是为了帮助shadergen工具生成在运行时动态设置baseColorMap所需的着色器。

MaterialRed.qml

PrincipledMaterial {
    baseColor: "red"
    lighting: PrincipledMaterial.NoLighting
}

MaterialRedExtended.qml

MaterialRed {
    baseColorMap: Texture {
        source: "maps/metallic/basecolor.jpg"
    }
}

main.qml

Model {
    position: Qt.vector3d(0, -30, 0)
    scale: Qt.vector3d(4, 4, 4)
    source: "#Sphere"
    materials: MaterialRed {
        id: redMaterial
    }
MouseArea {
    anchors.fill: parent
    onClicked: {
    if (redMaterial.baseColorMap === null)
        redMaterial.baseColorMap = baseColorMap
    else
        redMaterial.baseColorMap = null
    }
}

See also QtShaderTools.

请参见QtShaderTools。

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.