着色器生成工具

着色器生成工具是一个命令行应用程序，是Qt Quick 3D 资产调节管道的一部分。它可以在每个项目中启用，也可以通过命令行手动运行。预先生成材质着色器可以显著缩短启动时间和/或避免在运行时出现不必要的停滞，因为在运行时创建材质着色器的过程成本很高。

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

已知的限制有

• 具有多个View3D 的场景。
• 使用生成材质时，不支持动态添加或删除灯光。
• 生成的着色器与所使用的 Qt 版本密切相关，因为它依赖于渲染器的内部结构。因此，无法保证生成的着色器在不同版本之间的兼容性。

使用方法

要在项目中启用离线生成材质着色器，请在项目文件中添加以下内容：

CMake：

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

或者也可以像这样从命令行手动调用 shadergen 工具：

shadergen main.qml Material.qml

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

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

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

命令行参数

生成的内容

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

使用-d 参数调用 shadergen 工具可以查看 .qsbc 文件：

shadergen -d qtappshaders.qsbc

动态属性

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

下面的示例展示了一个假想的材质示例，我们希望在运行时为材质添加一个基色贴图。请注意，该示例中从未使用过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
    }
}