Shadergen-Werkzeug

Das Shadergen-Tool ist eine Befehlszeilenanwendung, die Teil der Asset-Konditionierungspipeline von Qt Quick 3D ist. Es kann pro Projekt aktiviert oder manuell über die Befehlszeile ausgeführt werden. Die Vorgenerierung der Material-Shader kann sich erheblich auf die Startzeit auswirken und/oder unerwünschte Verzögerungen zur Laufzeit vermeiden, da die Erstellung eines Material-Shaders zur Laufzeit sehr kostspielig sein kann.

Eines der größten Hindernisse für den Offline-Shader-Generator ist die Menge an verschiedenen Materialien, die generiert werden können, nicht nur basierend auf den Materialeigenschaften selbst, sondern auch darauf, wie der Rest der Szene aufgebaut ist; z. B. wirken sich Lichtanzahl, Lichttyp, Schatten usw. auf die generierten Shader aus. Wenn wir auch die dynamischen Eigenschaften berücksichtigen, kann die Anzahl der Material-Shader-Permutationen sehr schnell dazu führen, dass es nicht mehr machbar ist, sie alle zur Bauzeit zu generieren. Um die Anzahl der Shader, die das Tool generieren muss, zu begrenzen, versucht das Tool nur die Shader zu generieren, die es für die Anwendung für notwendig hält. Die im Tool verwendete Heuristik ist unter Umständen nicht immer in der Lage zu erkennen, welche Materialien generiert werden sollten, dies gilt insbesondere für Eigenschaften, die sich zur Laufzeit ändern. Um zu überprüfen, ob die Material-Shader erfolgreich und korrekt generiert wurden, sollte das Tool eine .qsbc-Datei erzeugt haben, die inspiziert werden kann, um zu überprüfen, ob der Inhalt mit dem von der Anwendung verwendeten Material übereinstimmt. Es ist auch möglich, zu überprüfen, ob das Material aus dem vorgefertigten Cache geladen wurde, indem man die Umgebungsvariable QT_RHI_SHADER_DEBUG=1 setzt und in der Debug-Ausgabe nach Hinweisen sucht, dass die Engine den vorgenerierten Shader erfolgreich geladen hat.

Bekannte Einschränkungen sind:

• Szenen mit mehr als einem View3D.
• Dynamisches Hinzufügen oder Entfernen von Lichtern wird bei der Verwendung von generierten Materialien nicht unterstützt.
• Die generierten Shader sind strikt an die verwendete Qt-Version gebunden, da diese von den Interna des Renderers abhängig ist. Die Kompatibilität der generierten Shader zwischen verschiedenen Versionen kann daher nicht garantiert werden.

Verwendung

Um die Offline-Generierung von Material-Shadern in Ihrem Projekt zu aktivieren, fügen Sie Folgendes zu Ihrer Projektdatei hinzu:

CMake:

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

Alternativ kann das shadergen-Tool auch manuell von der Kommandozeile aus aufgerufen werden, etwa so:

shadergen main.qml Material.qml

Normalerweise sollte das shadergen-Tool aus dem Projektordner Ihrer Anwendung gestartet werden, aber es ist auch möglich, das Tool anzuweisen, sein aktuelles Arbeitsverzeichnis über das Argument -C zu ändern.

Wenn kein Ausgabepfad angegeben wird, schreibt das Tool die generierten Dateien in das aktuelle Verzeichnis. Der Ausgabepfad kann mit der Option -o geändert werden.

Beachten Sie, dass das Tool die gesamte Szene und nicht nur die Materialien kennen muss, um die erwarteten Materialien zu generieren. So hat z.B. die Anzahl der Lichter in der Szene auch einen Einfluss darauf, wie die Materialien generiert werden, daher sollten alle relevanten qml-Dateien zur Liste der Dateien hinzugefügt werden, die das Tool verarbeiten muss.

Kommandozeilen-Argumente

Erstellter Inhalt

Die Hauptausgabedatei der Shadergen-Tools ist eine .qsbc-Datei. Die .qsbc-Datei enthält eine Sammlung von .qsb-Dateien sowie einige Metadaten über die verschiedenen Material-Shader, wie z. B. die eindeutige Eigenschaftszeichenfolge für jedes Material.

Die .qsbc-Datei kann durch den Aufruf des Shadergen-Tools mit dem Argument -d eingesehen werden:

shadergen -d qtappshaders.qsbc

Dynamische Eigenschaften

Da das Tool zur Erstellungszeit ausgeführt wird, hat es nur begrenzte Möglichkeiten, Rückschlüsse darauf zu ziehen, welche Eigenschaften sich zur Laufzeit ändern könnten. Eigenschaften, bei denen sich ein Wert nur innerhalb des Eigenschaftsbereichs ändert, z. B. der Rauheitswert, haben keine Auswirkungen auf den generierten Material-Shader, aber Eigenschaften, die entweder ein- oder ausgeschaltet sind, z. B. die Einstellung einer Image-Map zur Laufzeit, würden die Generierung eines anderen Materialtyps erfordern. Es wird daher empfohlen, alle Varianten eines Materials, die Eigenschaften im Material oder in der Szene aktivieren oder deaktivieren, als einzelne Komponenten zu deklarieren, damit das Tool die richtigen Material-Shader generieren kann.

Das folgende Beispiel zeigt ein konstruiertes Beispiel für ein Material, bei dem wir zur Laufzeit eine Basisfarbkarte zu einem Material hinzufügen wollen. Beachten Sie, dass die Komponente MaterialRedExtended in diesem Beispiel nie verwendet wird. Sie ist lediglich definiert, um dem Shadergen-Tool zu helfen, die Shader zu generieren, die benötigt werden, um die baseColorMap zur Laufzeit dynamisch zu setzen.

MaterialRed.qml

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

MaterialRedErweitert.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
    }
}