Shadergen 工具

Shadergen 工具是一款命令行应用程序，是Qt Quick 3D 资源预处理流程的一部分。它可以按项目启用，也可以通过命令行手动运行。 预生成材质着色器可以显著缩短启动时间，并/或避免运行时出现不必要的卡顿，因为在运行时创建材质着色器的过程可能消耗较大资源。

离线着色器生成器面临的最大障碍之一是可生成的材质种类繁多，这不仅取决于材质属性本身，还取决于场景其余部分的设置；例如，光源数量、光源类型、阴影等都会影响生成的着色器。 若再将动态属性纳入考量，材质着色器的组合数量会迅速激增，导致在构建时无法生成所有着色器。为了限制工具需要生成的着色器数量，该工具会尝试仅生成其认为应用程序所需的着色器。 该工具所使用的启发式算法可能无法始终准确检测出应生成哪些材质，对于运行时会发生变化的属性而言，这种情况尤为明显。 为了验证材质着色器是否已成功且正确地生成，该工具应已生成一个.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文件，以及关于各种材质着色器的元数据，例如每种材质的唯一属性字符串。要查看 .qsbc 文件的内容，可以使用 shadergen 工具的-l 参数，如下所示：

shadergen -l 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
    }
}