CustomMaterial QML Type

Basiskomponente zur Erstellung benutzerdefinierter Materialien, die zur Schattierung von Modellen verwendet werden. Mehr...

• Liste aller Elemente, einschließlich geerbter Elemente

Eigenschaften

• alwaysDirty : bool
• destinationAlphaBlend : enumeration (since 6.7)
• destinationBlend : enumeration
• fragmentShader : url
• lineWidth : real
• shadingMode : enumeration
• sourceAlphaBlend : enumeration (since 6.7)
• sourceBlend : enumeration
• vertexShader : url

Ausführliche Beschreibung

Das benutzerdefinierte Material ermöglicht die Verwendung von benutzerdefiniertem Shader-Code für ein Material und bietet so Programmierbarkeit auf der Ebene der Grafik-Shader. Es können Vertex-, Fragment- oder sowohl Vertex- als auch Fragment-Shader bereitgestellt werden. Die Eigenschaften „ vertexShader “ und „ fragmentShader “ sind URLs, die auf Dateien verweisen, welche Shader-Schnipsel enthalten, und funktionieren sehr ähnlich wie „ ShaderEffect “ oder „ Image.source “. Bei benutzerdefinierten Materialien werden nur die Schemata „ file “ und „ qrc “ unterstützt. Es ist auch möglich, das Schema „ file “ wegzulassen, wodurch auf bequeme Weise ein relativer Pfad angegeben werden kann. Ein solcher Pfad wird relativ zum Speicherort der Komponente (der Datei „ .qml “) aufgelöst.

Eine Einführung in benutzerdefinierte Materialien finden Sie auf der Seite „Programmierbare Materialien, Effekte, Geometrie und Texturdaten“.

Einführung

Betrachten Sie die folgenden Versionen derselben Szene. Auf der linken Seite verwendet der Zylinder ein integriertes, nicht programmierbares Material. Solche Materialien lassen sich über eine Vielzahl von Eigenschaften konfigurieren, es besteht jedoch keine weitere Kontrolle über die Shader, die im Hintergrund generiert werden. Auf der rechten Seite ist derselbe Zylinder nun mit einem „CustomMaterial“ verknüpft, das auf von der Anwendung bereitgestellte Vertex- und Fragment-Shader-Schnipsel verweist. Dies ermöglicht es, benutzerdefinierte, anwendungsspezifische Logik in den Vertex-Shader einzufügen, um die Geometrie zu transformieren, und bestimmte Farbeigenschaften im Fragment-Shader individuell festzulegen. Da es sich um ein benutzerdefiniertes Material vom Typ „ shaded “ handelt, wird der Zylinder weiterhin wie gewohnt in die Beleuchtung der Szene einbezogen.

View3D {
    anchors.fill: parent
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }
    camera: camera
    DirectionalLight {
        position: Qt.vector3d(-500, 500, -100)
        color: Qt.rgba(0.2, 0.2, 0.2, 1.0)
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }
    Model {
        source: "#Cylinder"
        eulerRotation: Qt.vector3d(30, 30, 0)
        scale: Qt.vector3d(1.5, 1.5, 1.5)
        materials: [
            DefaultMaterial {
                diffuseColor: Qt.rgba(0, 1, 0, 1)
            }
        ]
    }
}

View3D {
    anchors.fill: parent
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }
    camera: camera
    DirectionalLight {
        position: Qt.vector3d(-500, 500, -100)
        color: Qt.rgba(0.2, 0.2, 0.2, 1.0)
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }
    Model {
        source: "#Cylinder"
        eulerRotation: Qt.vector3d(30, 30, 0)
        scale: Qt.vector3d(1.5, 1.5, 1.5)
        materials: [
            CustomMaterial {
                vertexShader: "material.vert"
                fragmentShader: "material.frag"
                property real uTime
                property real uAmplitude: 50
                NumberAnimation on uTime { from: 0; to: 100; duration: 10000; loops: -1 }
            }
        ]
    }
}

Nehmen wir an, die Shader-Schnipsel in material.vert und material.frag lauten wie folgt:

void MAIN()
{
    VERTEX.x += sin(uTime + VERTEX.y) * uAmplitude;
}

void MAIN()
{
    BASE_COLOR = vec4(0.0, 1.0, 0.0, 1.0);
}

Beachten Sie, dass uTime und uAmplitude Eigenschaften des CustomMaterial-Elements sind. Ihre Werte können geändert und normal animiert werden; die Werte werden den Shadern automatisch zur Verfügung gestellt, ohne dass der Entwickler weitere Maßnahmen ergreifen muss.

Das Ergebnis ist ein Zylinder, dessen Scheitelpunkte animiert werden:

Zwei Varianten benutzerdefinierter Materialien

Es gibt zwei Haupttypen von benutzerdefinierten Materialien. Diese werden durch die Eigenschaft „ shadingMode “ festgelegt. Bei „ unshaded “-Materialien gibt der Fragment-Shader eine einzige „ vec4 “-Farbe aus und ignoriert dabei Lichter, Lichtproben und Schatten in der Szene. Bei „ shaded “-Materialien wird vom Shader erwartet, dass er bestimmte Funktionen implementiert und mit integrierten Variablen arbeitet, um Beleuchtung und Schattenbeiträge zu berücksichtigen.

Die Standardauswahl ist in der Regel ein „shaded“ Material; dies spiegelt sich im Standardwert der Eigenschaft „ shadingMode “ wider. Dies eignet sich für Materialien, die Scheitelpunkte oder andere eingehende Daten aus der Geometrie transformieren oder Werte wie „ BASE_COLOR “ oder „ EMISSIVE_COLOR “ auf benutzerdefinierte Weise ermitteln müssen – beispielsweise durch Abtasten von „ SCREEN_TEXTURE “ oder „ DEPTH_TEXTURE “ –, während sie weiterhin Licht- und Schattenbeiträge aus der Szene empfangen. Darüber hinaus können solche Materialien auch die Gleichungen überschreiben und neu implementieren, die zur Berechnung der Beiträge von Richt-, Punkt- und anderen Lichtquellen verwendet werden. Die von der Anwendung bereitgestellten Shader-Schnipsel werden hinter den Kulissen von der „ Qt Quick 3D “-Engine stark angepasst, um die Funktionen bereitzustellen, über die Standardmaterialien verfügen, wie beispielsweise die Beleuchtung.

Unschattierte Materialien sind nützlich, wenn das Erscheinungsbild des Objekts vollständig durch den benutzerdefinierten Shader-Code bestimmt wird. Die Shader für solche Materialien werden von der Engine nur minimal ergänzt, sodass es vollständig dem Shader überlassen bleibt, die endgültige Fragmentfarbe zu bestimmen. Dies bietet mehr Freiheit, schränkt jedoch auch die Möglichkeiten zur Integration mit anderen Elementen der Szene, wie beispielsweise Lichtquellen, ein.

Bereitstellung von Daten für die Shader

Die dynamischen Eigenschaften des `CustomMaterial` können mithilfe von QML und den Funktionen unter Qt Quick geändert und animiert werden, wobei die Werte automatisch an die Shader weitergegeben werden. Dies ähnelt in der Praxis sehr dem Verfahren unter ShaderEffect. Die folgende Liste zeigt, wie die Eigenschaften zugeordnet werden:

• bool, int, real -> bool, int, float
• QColor, ` color ` -> `vec4`, und die Farbe wird in den linearen Farbraum konvertiert, wobei für den in QML angegebenen Farbwert der sRGB-Farbraum vorausgesetzt wird. Die integrierten Qt-Farben, wie z. B. ` "green" `, liegen ebenfalls im sRGB-Farbraum, und für alle Farbeigenschaften von `DefaultMaterial` und ` PrincipledMaterial` wird dieselbe Konvertierung durchgeführt, sodass dieses Verhalten von `CustomMaterial` mit diesen übereinstimmt. Im Gegensatz zu „ Qt Quick “ ist bei „ Qt Quick 3D “ die Linearisierung unerlässlich, da in der Regel ein Tonemapping auf die 3D-Szene angewendet wird.
• QRect, QRectF, rect -> vec4
• QPoint, QPointF, point, QSize, QSizeF, size -> vec2
• QVector2D, vector2d -> vec2
• QVector3D, vector3d -> vec3
• QVector4D, vector4d -> vec4
• QMatrix4x4, matrix4x4 -> mat4
• QQuaternion, quaternion -> vec4, der Skalarwert ist w
• TextureInput -> „sampler2D“ oder „samplerCube“, je nachdem, ob „ Texture “ oder „ CubeMapTexture “ in der Textur-Eigenschaft von „ TextureInput “ verwendet wird. Das Setzen der Eigenschaft „ enabled “ auf „false“ führt dazu, dass dem Shader eine Dummy-Textur zur Verfügung gestellt wird, was bedeutet, dass die Shader weiterhin funktionsfähig sind, jedoch eine Textur mit undurchsichtigem schwarzem Bildinhalt abtasten. Beachten Sie, dass Eigenschaften für Sampler immer auf ein ` TextureInput `-Objekt verweisen müssen und nicht direkt auf ein ` Texture `. Was die Eigenschaften von „ Texture “ betrifft, so werden bei benutzerdefinierten Materialien nur die Eigenschaften in Bezug auf Quelle, Kachelung und Filterung implizit berücksichtigt, während die Umsetzung der übrigen Eigenschaften (wie z. B. UV-Transformationen) den benutzerdefinierten Shadern überlassen bleibt, die diese nach eigenem Ermessen implementieren können.

Nicht schattierte benutzerdefinierte Materialien

Im Folgenden finden Sie ein Beispiel für ein benutzerdefiniertes Material vom Typ „ unshaded “.

CustomMaterial {
    // These properties are automatically exposed to the shaders
    property real time: 0.0
    property real amplitude: 5.0
    property real alpha: 1.0
    property TextureInput tex: TextureInput {
        enabled: true
        texture: Texture { source: "image.png" }
    }

    shadingMode: CustomMaterial.Unshaded
    sourceBlend: alpha < 1.0 ? CustomMaterial.SrcAlpha : CustomMaterial.NoBlend
    destinationBlend: alpha < 1.0 ? CustomMaterial.OneMinusSrcAlpha : CustomMaterial.NoBlend
    cullMode: CustomMaterial.BackFaceCulling

    vertexShader: "customshader.vert"
    fragmentShader: "customshader.frag"
}

Im obigen Beispiel könnten die unshaded -Schnipsel für Vertex- und Fragment-Shader wie folgt aussehen. Beachten Sie, dass die Shader keine Uniforms oder Vertex-Eingaben deklarieren und dies auch nicht dürfen, da dies von Qt beim Zusammenstellen des endgültigen Shader-Codes übernommen wird.

VARYING vec3 pos;
VARYING vec2 texcoord;

void MAIN()
{
    pos = VERTEX;
    pos.x += sin(time * 4.0 + pos.y) * amplitude;
    texcoord = UV0;
    POSITION = MODELVIEWPROJECTION_MATRIX * vec4(pos, 1.0);
}

VARYING vec3 pos;
VARYING vec2 texcoord;

void MAIN()
{
    vec4 c = texture(tex, texcoord);
    FRAGCOLOR = vec4(pos.x * 0.02, pos.y * 0.02, pos.z * 0.02, alpha) * c;
}

Die folgenden speziellen Schlüsselwörter in Großbuchstaben stehen zur Verfügung:

• MAIN -> Der Name des Einstiegspunkts im Vertex- oder Fragment-Shader-Schnipsel muss immer „ MAIN “ lauten. Die Angabe dieser Funktion ist in Shader-Schnipseln für nicht schattierte benutzerdefinierte Materialien obligatorisch.
• VARYING -> deklariert einen Ausgang des Vertex-Shaders oder einen Eingang des Fragment-Shaders
• POSITION -> vec4, die Ausgabe aus dem Vertex-Shader
• FRAGCOLOR -> vec4, die Ausgabe aus dem Fragment-Shader. Nur für nicht schattierte benutzerdefinierte Materialien verfügbar.
• VERTEX -> vec3, die Vertex-Position im Vertex-Shader.
• NORMAL -> vec3, die Vertex-Normale im Vertex-Shader. Wenn das Mesh für das zugehörige Modell keine Normalen bereitstellt, ist der Wert vec3(0,0).
• UV0 -> vec2, der erste Satz von Texturkoordinaten im Vertex-Shader. Wenn das Mesh des zugehörigen Modells keine Texturkoordinaten bereitstellt, ist der Wert vec2(0,0).
• UV1 -> vec2, der zweite Satz von Texturkoordinaten im Vertex-Shader. Wenn das Mesh des zugehörigen Modells keinen zweiten Satz von Texturkoordinaten bereitstellt, lautet der Wert vec2(0,0).
• COLOR -> vec4, die Vertexfarbe im Vertex-Shader. Wenn das Mesh für das zugehörige Modell keine Farben pro Vertex bereitstellt, lautet der Wert vec4(1.0).
• TANGENT -> vec3, Tangente im Vertex-Shader. Wenn das Mesh des zugehörigen Modells keine Tangentendaten bereitstellt, lautet der Wert vec3(0,0).
• BINORMAL -> vec3, Binormal im Vertex-Shader. Wenn das Mesh des zugehörigen Modells keine Binormal-Daten bereitstellt, lautet der Wert vec3(0,0).
• JOINTS -> ivec4, Gelenkindizes im Vertex-Shader. Wenn das Mesh des zugehörigen Modells keine Daten zu den Gelenkindizes bereitstellt, lautet der Wert ivec4(0).
• WEIGHTS -> vec4, Gelenkgewichte im Vertex-Shader. Wenn das Mesh des zugehörigen Modells keine Daten zu den Gelenkgewichten bereitstellt, lautet der Wert vec4(0.0).
• MORPH_POSITION(n) -> vec3, die Position des n+1.Morph-Ziels im Vertex-Shader. Das zugehörige Modell sollte entsprechende Daten bereitstellen.
• MORPH_NORMAL(n) -> vec3, die n+1.Morph-Zielnormale im Vertex-Shader. Das zugehörige Modell sollte entsprechende Daten bereitstellen.
• MORPH_TANGENT(n) -> vec3, die Tangente des n+1.Morph-Ziels im Vertex-Shader. Das zugehörige Modell sollte entsprechende Daten bereitstellen.
• MORPH_BINORMAL(n) -> vec3, die n+1.Binormale des Morph-Ziels im Vertex-Shader. Das zugehörige Modell sollte entsprechende Daten bereitstellen.
• MODELVIEWPROJECTION_MATRIX -> mat4, die Modell-Ansicht-Projektionsmatrix. Projektionsmatrizen folgen stets den OpenGL-Konventionen, mit einer fest integrierten Transformation für die Richtung der Y-Achse und die Clip-Tiefe, abhängig von der zur Laufzeit verwendeten Grafik-API.
• VIEWPROJECTION_MATRIX -> mat4, die View-Projektionsmatrix
• PROJECTION_MATRIX -> mat4, die Projektionsmatrix
• INVERSE_PROJECTION_MATRIX -> mat4, die inverse Projektionsmatrix
• VIEW_MATRIX -> mat4, die Ansicht- (Kamera-)Matrix
• MODEL_MATRIX -> mat4, die Modell- (Welt-)Matrix
• NORMAL_MATRIX -> mat3, die Normalmatrix (die Transponierte der Inversen des oberen linken 3x3-Teils der Modellmatrix)
• BONE_TRANSFORMS -> mat4[], das Array der Knochenmatrizen des Modells
• BONE_NORMAL_TRANSFORMS -> mat3[], das Array der Knochen-Normalmatrizen des Modells (die Transponierte der Inversen des oberen linken 3x3-Teils der jeweiligen Knochenmatrizen)
• MORPH_WEIGHTS -> float[], das Array der Morph-Gewichte. Das zugehörige Modell sollte die entsprechenden Daten bereitstellen. Aus Sicherheitsgründen ist QT_MORPH_MAX_COUNT auf die Größe dieses Arrays festgelegt.
• CAMERA_POSITION -> vec3, die Kameraposition im Weltraum
• CAMERA_DIRECTION -> vec3, der Kamerarichtungsvektor
• CAMERA_PROPERTIES -> vec2, die Werte für den nahen und fernen Clip der Kamera
• POINT_SIZE -> float, nur im Vertex-Shader beschreibbar. Beim Rendern von Geometrie mit einer Topologie aus Punkten muss der benutzerdefinierte Vertex-Shader diesen Wert entweder auf 1,0 oder einen anderen Wert setzen, sowohl bei schattierten als auch bei unschattierten benutzerdefinierten Materialien. Weitere Hinweise zur Unterstützung von Werten ungleich 1 finden Sie unter PrincipledMaterial::pointSize.

Geschattete benutzerdefinierte Materialien

Ein Material vom Typ „ shaded “ augments den Shader-Code, der von einem „ PrincipledMaterial “ generiert würde. Im Gegensatz zu ungeschatteten Materialien, die fast die gesamte Logik für die Hauptfunktionen des Vertex- und Fragment-Shaders selbst bereitstellen und somit das Hinzufügen von generiertem Code für Beleuchtung, Schattenwurf, globale Beleuchtung usw. verhindern, lassen geschattete Materialien die Shader-Generierung normal ablaufen, als wäre das „CustomMaterial“ ein „ PrincipledMaterial “. Die Vertex- und Fragment-Shader-Schnipsel sollen optionale Funktionen bereitstellen, die dann an bestimmten Stellen aufgerufen werden, wodurch die Möglichkeit besteht, die Farben und andere Werte anzupassen, die anschließend für die Berechnung der Beleuchtung und der endgültigen Fragmentfarbe verwendet werden.

Anstatt lediglich eine ` MAIN `-Funktion zu implementieren, kann der Fragment-Shader für ein „shaded“ benutzerdefiniertes Material mehrere Funktionen implementieren. Alle Funktionen, einschließlich ` MAIN`, können in „shaded“ benutzerdefinierten Materialien optional implementiert werden. Ein leeres Shader-Snippet oder sogar das vollständige Weglassen der Eigenschaften ` vertexShader ` oder ` fragmentShader ` ist ebenfalls völlig zulässig.

Vertex-Shader-Schnipsel in einem benutzerdefinierten Material mit Schattierung

Die folgenden Funktionen können in einem Vertex-Shader-Schnipsel implementiert werden:

• void MAIN() Sofern vorhanden, wird diese Funktion aufgerufen, um den Wert von „ POSITION “ – die „vec4“-Ausgabe des Vertex-Shaders – festzulegen und optional die Werte von „ VERTEX “, „ COLOR “, „ NORMAL “, „ UV0 “, „ UV1 “ und „ TANGENT “ , BINORMAL, JOINTS und WEIGHTS. Anders als bei nicht schattierten Materialien ist das Schreiben in diese Variablen sinnvoll, da die geänderten Werte anschließend im restlichen generierten Shader-Code berücksichtigt werden (während bei nicht schattierten Materialien kein zusätzlicher Shader-Code generiert wird). Wenn der benutzerdefinierte Vertex-Shader beispielsweise die Scheitelpunkte oder die Normalen verschiebt, muss er die geänderten Werte in „ VERTEX “ oder „ NORMAL “ speichern, um anschließend korrekte Beleuchtungsberechnungen zu erzielen. Zudem kann die Funktion in Variablen schreiben, die mit „ VARYING “ definiert wurden, um interpolierte Daten an den Fragment-Shader zu übergeben. Wenn diese Funktion oder eine Neudefinition von „ POSITION “ nicht vorhanden ist, wird „ POSITION “ auf der Grundlage von „ VERTEX “ und „ MODELVIEWPROJECTION_MATRIX “ berechnet, genau wie es ein „ PrincipledMaterial “ tun würde.

  Beispiel, bei dem sowohl auf als Uniforms exponierte QML-Eigenschaften zurückgegriffen wird als auch Daten an den Fragment-Shader übergeben werden:

  VARYING vec3 vNormal;
  VARYING vec3 vViewVec;
  
  void MAIN()
  {
      VERTEX.x += sin(uTime * 4.0 + VERTEX.y) * uAmplitude;
      vNormal = normalize(NORMAL_MATRIX * NORMAL);
      vViewVec = CAMERA_POSITION - (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
      POSITION = MODELVIEWPROJECTION_MATRIX * vec4(VERTEX, 1.0);
  }

  Hinweis: Im obigen Beispiel ist die Zuweisung eines Werts an ` POSITION ` optional, da die Verwendung in diesem Fall mit dem Standardverhalten identisch ist.

Fragment-Shader-Ausschnitte in einem schattierten benutzerdefinierten Material

Die folgenden Funktionen können in einem Fragment-Shader-Ausschnitt implementiert werden:

• void MAIN() Sofern vorhanden, wird diese Funktion aufgerufen, um die Werte der speziellen beschreibbaren Variablen „ BASE_COLOR “, „ METALNESS “, „ ROUGHNESS “ , SPECULAR_AMOUNT, NORMAL, CLEARCOAT_FRESNEL_POWER, CLEARCOAT_FRESNEL_SCALE, CLEARCOAT_FRESNEL_BIAS, CLEARCOAT_AMOUNT, CLEARCOAT_ROUGHNESS, CLEARCOAT_NORMAL, FRESNEL_BIAS, FRESNEL_SCALE, FRESNEL_POWER, IOR, TRANSMISSION_FACTOR, THICKNESS_FACTOR, ATTENUATION_COLOR, ATTENUATION_DISTANCE und OCCLUSION_AMOUNT.

  Ein häufiger Anwendungsfall ist die Festlegung des Werts für „ BASE_COLOR “ auf der Grundlage einer Texturabtastung, sei es eine Grundfarbkarte, „ SCREEN_TEXTURE “ oder eine andere Art von Quelle. Dies kann insbesondere dann relevant und praktisch sein, wenn keine benutzerdefinierten Lichtverarbeitungsfunktionen implementiert sind. Durch das Setzen von „ BASE_COLOR.a “ auf einen anderen Wert als den Standardwert 1,0 lässt sich der endgültige Alpha-Wert des Fragments beeinflussen. (Beachten Sie, dass hierfür häufig auch die Aktivierung von Alpha-Blending unter sourceBlend und destinationBlend erforderlich ist.)

  Ein weiteres Szenario tritt auf, wenn keine benutzerdefinierte Funktion „ SPECULAR_LIGHT “ bereitgestellt wird oder wenn in „ SceneEnvironment “ eine Lichtprobe festgelegt ist. Die Werte für „Metalness“, „Roughness“ und andere Parameter, die die Berechnung des spekularen Beitrags beeinflussen, können in „ MAIN “ auf die gewünschten benutzerdefinierten Werte gesetzt werden.

  Die Funktion kann in die folgenden speziellen Variablen schreiben. Die in diese Variablen geschriebenen Werte sind in der Regel entweder fest codiert oder werden auf der Grundlage von QML-Eigenschaften berechnet, die auf „Uniforms“ abgebildet sind. Die Semantik entspricht der von ` PrincipledMaterial`.

  • vec4 BASE_COLOR – Die Grundfarbe und der Material-Alpha-Wert. Entspricht dem „ built-in materials' color property “. Wenn Funktionen des Lichtprozessors nicht implementiert sind, kann es sinnvoll sein, eine benutzerdefinierte Grundfarbe in „ MAIN “ festzulegen, da diese dann bei den Standard-Beleuchtungsberechnungen berücksichtigt wird. Der Standardwert ist „ vec4(1.0) “, was Weiß mit einem Alpha-Wert von 1,0 bedeutet. Der Alpha-Wert beeinflusst den endgültigen Alpha-Wert des Fragments. Der endgültige Alpha-Wert ergibt sich aus der Opazität des Objekts (Modells) multipliziert mit dem Alpha-Wert der Grundfarbe. Wenn Sie den Wert direkt im Shader-Code festlegen und sich nicht auf die über die Farbeigenschaften in QML bereitgestellten Uniform-Werte verlassen, beachten Sie bitte, dass es dem Shader obliegt, bei Bedarf die Konvertierung von sRGB in lineare Farben durchzuführen. Angenommen, es gelten die Werte ` vec3 color ` und ` float alpha `, lässt sich dies beispielsweise wie folgt umsetzen:

    float C1 = 0.305306011;
    vec3 C2 = vec3(0.682171111, 0.682171111, 0.682171111);
    vec3 C3 = vec3(0.012522878, 0.012522878, 0.012522878);
    BASE_COLOR = vec4(rgb * (rgb * (rgb * C1 + C2) + C3), alpha);

  • vec3 EMISSIVE_COLOR – Die Farbe der Eigenbeleuchtung. Entspricht der Emissionsfarbe der integrierten Materialien, die sich aus built-in materials's emissiveFactor property und built-in materials's emissiveMap property zusammensetzt. Der Standardwert ist vec3(0.0). Wenn Sie den Wert direkt im Shader-Code festlegen und sich nicht auf die aus den Farbeigenschaften in QML bereitgestellten Uniform-Werte verlassen, beachten Sie bitte, dass es Aufgabe des Shaders ist, bei Bedarf die Konvertierung von sRGB in lineare Farben durchzuführen.
  • float IOR Gibt den Brechungsindex des Materials an. Ein typischer Wert und zugleich der Standardwert ist 1.5, da dies dem Wert entspricht, den ein PrincipledMaterial verwenden würde.
  • PrincipledMaterial float TRANSMISSION_FACTOR Legt den Grad der Transluzenz fest. Ein typischer Wert – und zugleich der Standardwert – wäre 1.0, da dies dem Wert entspricht, den ein 0.0 verwenden würde.
  • float THICKNESS_FACTOR Legt die Dicke des durchscheinenden Materials fest. Ein typischer Wert wäre 10.0, und der Standardwert ist 0.0, da dies dem Wert entspricht, den ein „ PrincipledMaterial “ verwenden würde.
  • vec3 ATTENUATION_COLOR Legt die Farbverschiebung des durchscheinenden Materials in Abhängigkeit von der Entfernung fest. Ein typischer Wert wäre vec3(1.0, 0.0, 0.0), und der Standardwert ist vec3(1.0), da dies dem Wert entspricht, den ein „ PrincipledMaterial “ verwenden würde.
  • float ATTENUATION_DISTANCE Legt die Abnahme der Farbverschiebung des durchscheinenden Materials in Abhängigkeit von der Entfernung fest. Ein typischer Wert wäre 100.0, und der Standardwert ist 0.0, da dies dem Wert entspricht, den ein PrincipledMaterial verwenden würde.
  • float METALNESS Metallizitätsgrad im Bereich von 0,0 bis 1,0. Der Standardwert ist 0. Muss auf einen Wert ungleich Null gesetzt werden, um wirksam zu sein.
  • float ROUGHNESS Rauheitswert im Bereich von 0,0 bis 1,0. Der Standardwert ist 0.
  • float CLEARCOAT_FRESNEL_POWER Gibt die Fresnel-Stärke der Klarlackschicht an. Ein typischer Wert und zugleich der Standardwert ist „ 5.0 “, da dies dem Wert entspricht, den ein „ PrincipledMaterial “ verwenden würde.
  • float CLEARCOAT_FRESNEL_SCALE Legt den Fresnel-Maßstab der Klarlackschicht fest. Ein typischer Wert und zugleich der Standardwert ist 1.0, da dies dem Wert entspricht, den ein PrincipledMaterial verwenden würde.
  • float CLEARCOAT_FRESNEL_BIAS Legt den Fresnel-Bias der Klarlackschicht fest. Ein typischer Wert und zugleich der Standardwert ist 0.0, da dies der Wert ist, den ein „ PrincipledMaterial “ verwenden würde.
  • float CLEARCOAT_AMOUNT Legt die Dicke der Klarlackschicht auf dem Material fest. Ein typischer Wert wäre 1.0, und der Standardwert ist 0.0, da dies dem Wert entspricht, den ein „ PrincipledMaterial “ verwenden würde.
  • float CLEARCOAT_ROUGHNESS Legt die Rauheit der Klarlackschicht fest. Ein typischer Wert wäre 1.0 für eine vollständig verwischte Klarlackschicht; der Standardwert ist 0.0, da dies der Wert ist, den ein PrincipledMaterial verwenden würde.
  • vec3 CLEARCOAT_NORMAL – Die Normale der Klarlackschicht, die vom Vertex-Shader im Weltraum stammt. Obwohl diese Eigenschaft denselben Anfangswert wie VAR_WORLD_NORMAL hat, wirkt sich nur eine Änderung des Werts von CLEARCOAT_NORMAL auf die Normale der Klarlackschicht aus.
  • float FRESNEL_POWER Legt die Fresnel-Stärke fest. Ein typischer Wert und zugleich der Standardwert ist 5.0, da dies dem Wert entspricht, den ein „ PrincipledMaterial “ verwenden würde.
  • float FRESNEL_SCALE Legt den Fresnel-Maßstab fest. Ein typischer Wert und zugleich der Standardwert ist 1.0, da dies der Wert ist, den ein PrincipledMaterial verwenden würde.
  • float FRESNEL_BIAS Legt den Fresnel-Bias fest. Ein typischer Wert und zugleich der Standardwert ist „ 0.0 “, da dies dem Wert entspricht, den ein „ PrincipledMaterial “ verwenden würde.
  • float SPECULAR_AMOUNT Spiegelungsintensität im Bereich von 0,0 bis 1,0. Der Standardwert ist 0.5 und entspricht damit PrincipledMaterial::specularAmount. Muss auf einen Wert ungleich Null gesetzt werden, um wirksam zu sein.
  • float OCCLUSION_AMOUNT Legt den AO-Faktor fest. Ein typischer Wert und zugleich der Standardwert ist 1.0, da dies dem Wert entspricht, den ein PrincipledMaterial verwenden würde.
  • vec3 NORMAL – Die Normale, die vom Vertex-Shader im Weltraum stammt. Obwohl diese Eigenschaft denselben Anfangswert wie VAR_WORLD_NORMAL hat, wirkt sich nur eine Änderung des Werts von NORMAL auf die Beleuchtung aus.
  • vec3 TANGENT – Die Tangente, die vom Vertex-Shader im Weltraumkoordinatensystem stammt. Dieser Wert wird möglicherweise hinsichtlich der beidseitigen Darstellung angepasst.
  • vec3 BINORMAL – Die Binormale, die vom Vertex-Shader im Weltraum stammt. Dieser Wert wird möglicherweise hinsichtlich der beidseitigen Darstellung angepasst.
  • vec2 UV0 – Der erste Satz von Texturkoordinaten aus dem Vertex-Shader. Diese Eigenschaft ist im Fragment-Shader schreibgeschützt.
  • vec2 UV1 – Der zweite Satz von Texturkoordinaten aus dem Vertex-Shader. Diese Eigenschaft ist im Fragment-Shader schreibgeschützt.

  Hinweis: Anders als bei ungeschatteten Materialien hat der Fragment- MAIN bei einem geschatteten Material keinen direkten Einfluss auf „ FRAGCOLOR “. Vielmehr bestimmen die in den Lichtprozessorfunktionen geschriebenen Werte „ DIFFUSE “ und „ SPECULAR “, wie die endgültige Fragmentfarbe aussieht. Wenn eine Lichtprozessorfunktion nicht implementiert ist, werden die entsprechenden Standard-Schattierungsberechnungen wie bei einem „ PrincipledMaterial “ durchgeführt, wobei „ BASE_COLOR “ und andere Werte aus der obigen Liste berücksichtigt werden.

  Ein Beispiel für einen einfachen, metallischen benutzerdefinierten Material-Shader könnte wie folgt aussehen:

  void MAIN()
  {
      METALNESS = 1.0;
      ROUGHNESS = 0.5;
      FRESNEL_POWER = 5.0;
  }

  Ein weiteres Beispiel, bei dem die Grundfarbe und der Alpha-Wert durch das Abtasten einer Textur festgelegt werden:

  VARYING vec2 texcoord;
  void MAIN()
  {
      BASE_COLOR = texture(uColorMap, texcoord);
  }

• void AMBIENT_LIGHT() Sofern vorhanden, wird diese Funktion einmal pro Fragment aufgerufen. Die Aufgabe der Funktion besteht darin, den gesamten Beitrag der Umgebungsbeleuchtung zu einer beschreibbaren Spezialvariablen „ DIFFUSE “ hinzuzufügen. Sie kann natürlich auch einen anderen Wert berechnen oder „ DIFFUSE “ gar nicht verändern (um die Umgebungsbeleuchtung vollständig zu ignorieren). Ist diese Funktion überhaupt nicht vorhanden, wird der Umgebungslichtbeitrag wie gewohnt berechnet, so wie es ein „ PrincipledMaterial “ tun würde.

  Die Funktion kann in die folgenden Spezialvariablen schreiben:

  • vec3 ` DIFFUSE `: Sammelt die Beiträge des diffusen Lichts pro Fragment. Die Lichtprozessorfunktionen addieren typischerweise `(+=)` dazu, da durch das Überschreiben des Werts der Beitrag anderer Lichtquellen verloren gehen würde.

  Die Funktion kann zusätzlich zu den in der obigen Tabelle aufgeführten Matrix- (z. B. MODEL_MATRIX) und Vektor-Uniforms (z. B. CAMERA_POSITION) die folgenden Spezialvariablen lesen:

  • vec3 TOTAL_AMBIENT_COLOR Der gesamte Umgebungslichtbeitrag in der Szene.

  Beispiel:

  void AMBIENT_LIGHT()
  {
      DIFFUSE += TOTAL_AMBIENT_COLOR;
  }

• void DIRECTIONAL_LIGHT() Sofern vorhanden, wird diese Funktion für jedes aktive Richtungslicht in der Szene für jedes Fragment aufgerufen. Die Aufgabe der Funktion besteht darin, den diffusen Beitrag zu einer beschreibbaren Spezialvariablen „ DIFFUSE “ hinzuzufügen. Die Funktion kann auch nichts tun; in diesem Fall werden die diffusen Beiträge von Richtlichtern ignoriert. Wenn die Funktion überhaupt nicht vorhanden ist, werden die diffusen Beiträge von Richtlichtern wie bei einem „ PrincipledMaterial “ normal akkumuliert.

  Die Funktion kann in die folgenden Spezialvariablen schreiben:

  • vec3 „ DIFFUSE “ Sammelt die diffusen Lichtbeiträge pro Fragment. Die Lichtprozessorfunktionen addieren in der Regel (+=) dazu, da durch das Überschreiben des Werts der Beitrag anderer Lichter verloren gehen würde.

  Die Funktion kann zusätzlich zu den in der obigen Tabelle aufgeführten Matrix- (z. B. MODEL_MATRIX) und Vektor-Uniforms (z. B. CAMERA_POSITION) die folgenden Spezialvariablen lesen:

  • vec3 LIGHT_COLOR Farbe des diffusen Lichts.
  • float SHADOW_CONTRIB Schattenbeitrag oder 1,0, wenn überhaupt keine Schatten vorhanden sind oder keine Schatten empfangen werden.
  • vec3 TO_LIGHT_DIR Vektor, der in Richtung der Lichtquelle zeigt.
  • vec3 NORMAL Der Normalvektor im Weltraum.
  • vec4 BASE_COLOR Die Grundfarbe und der Material-Alpha-Wert.
  • float METALNESS Der Metalness-Wert.
  • float ROUGHNESS Der Roughness-Wert.

  Beispiel:

  void DIRECTIONAL_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void POINT_LIGHT() Sofern vorhanden, wird diese Funktion für jedes aktive Punktlicht in der Szene für jedes Fragment aufgerufen. Die Aufgabe der Funktion besteht darin, den diffusen Beitrag zu einer beschreibbaren Spezialvariablen „ DIFFUSE “ hinzuzufügen. Die Funktion kann auch nichts tun; in diesem Fall werden die diffusen Beiträge von Punktlichtquellen ignoriert. Wenn die Funktion überhaupt nicht vorhanden ist, werden die diffusen Beiträge von Punktlichtquellen wie bei einem „ PrincipledMaterial “ normal akkumuliert.

  Die Funktion kann in die folgenden Spezialvariablen schreiben:

  • vec3 DIFFUSE Sammelt die diffusen Lichtbeiträge pro Fragment.

  Die Funktion kann zusätzlich zu den in der obigen Tabelle aufgeführten Matrix- (z. B. MODEL_MATRIX) und Vektor-Uniforms (z. B. CAMERA_POSITION) die folgenden Spezialvariablen lesen:

  • vec3 LIGHT_COLOR Farbe des diffusen Lichts.
  • float LIGHT_ATTENUATION Lichtabschwächung.
  • float SHADOW_CONTRIB Schattenbeitrag oder 1,0, wenn überhaupt keine Schatten geworfen werden oder keine Schatten empfangen werden.
  • vec3 TO_LIGHT_DIR Vektor, der in Richtung der Lichtquelle zeigt.
  • vec3 NORMAL Der Normalvektor im Weltraum.
  • vec4 BASE_COLOR Die Grundfarbe und der Material-Alpha-Wert.
  • float METALNESS Der Metalness-Wert.
  • float ROUGHNESS Der Roughness-Wert.

  Beispiel:

  void POINT_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void SPOT_LIGHT() Sofern vorhanden, wird diese Funktion für jedes aktive Spotlicht in der Szene und für jedes Fragment aufgerufen. Die Aufgabe der Funktion besteht darin, den diffusen Beitrag zu einer beschreibbaren Spezialvariablen DIFFUSE hinzuzufügen. Die Funktion kann auch nichts tun; in diesem Fall werden die diffusen Beiträge von Spotlichtern ignoriert. Ist die Funktion überhaupt nicht vorhanden, werden die diffusen Lichtanteile der Spotlichter wie bei einem „ PrincipledMaterial “ normal akkumuliert.

  Die Funktion kann in die folgenden Spezialvariablen schreiben:

  • vec3 DIFFUSE Akkumuliert die diffusen Lichtanteile pro Fragment.

  Die Funktion kann zusätzlich zu den in der obigen Tabelle aufgeführten Matrix- (z. B. MODEL_MATRIX) und Vektor-Uniforms (z. B. CAMERA_POSITION) die folgenden speziellen Variablen lesen:

  • vec3 LIGHT_COLOR Farbe
  • des
  • diffusen Lichts.
  • float LIGHT_ATTENUATION Lichtabschwächung.
  • float SHADOW_CONTRIB Schattenbeitrag oder 1,0, wenn überhaupt keine Schatten vorhanden sind oder keine Schatten empfangen werden.
  • vec3 TO_LIGHT_DIR Vektor, der in Richtung der Lichtquelle zeigt.
  • float SPOT_FACTOR Spotlichtfaktor.
  • vec3 NORMAL Der Normalenvektor im Weltraum.
  • vec4 BASE_COLOR Die Grundfarbe und der Material-Alpha-Wert.
  • float METALNESS Der Metalness-Wert.
  • float ROUGHNESS Der Roughness-Wert.

  Beispiel:

  void SPOT_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SPOT_FACTOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void SPECULAR_LIGHT() Sofern vorhanden, wird diese Funktion für jedes aktive Licht in der Szene und für jedes Fragment aufgerufen. Die Aufgabe der Funktion besteht darin, den Spiegelungsbeitrag zu einer beschreibbaren Spezialvariablen SPECULAR hinzuzufügen. Die Funktion kann auch nichts tun; in diesem Fall werden die Spiegelungsbeiträge der Lichter ignoriert. Ist die Funktion überhaupt nicht vorhanden, werden die Spiegelungsbeiträge der Lichtquellen wie bei einem „ PrincipledMaterial “ normal akkumuliert.

  Die Funktion kann in die folgenden Spezialvariablen schreiben:

  • vec3 SPECULAR Akkumuliert die Spiegelungsbeiträge der Lichtquellen pro Fragment. Die Lichtprozessorfunktionen addieren in der Regel (+=) dazu, da durch das Überschreiben des Werts der Beitrag anderer Lichtquellen verloren gehen würde.

  Die Funktion kann zusätzlich zu den in der obigen Tabelle aufgeführten Matrix- (z. B. MODEL_MATRIX) und Vektor-Uniforms (z. B. CAMERA_POSITION) die folgenden speziellen Variablen lesen:

  • vec3 LIGHT_COLOR Farbe des Spiegelungslichts.
  • float LIGHT_ATTENUATION Lichtabschwächung. Bei Richtlicht beträgt der Wert 1,0. Bei Spotlicht entspricht der Wert dem Wert „ LIGHT_ATTENUATION * SPOT_FACTOR “ in „ void SPOT_LIGHT() “.
  • float SHADOW_CONTRIB Schattenbeitrag oder 1,0, wenn überhaupt keine Schatten geworfen werden oder keine Schatten empfangen werden.
  • vec3 FRESNEL_CONTRIB Fresnel-Beitrag aus der integrierten Fresnel-Berechnung.
  • vec3 TO_LIGHT_DIR Vektor, der in Richtung der Lichtquelle zeigt.
  • vec3 NORMAL Der Normalenvektor im Weltraum.
  • vec4 BASE_COLOR Die Grundfarbe und der Material-Alpha-Wert.
  • float METALNESS Der Metalness-Wert.
  • float ROUGHNESS Der Roughness-Wert.
  • float SPECULAR_AMOUNT Der Wert für die Spiegelung. Dieser Wert liegt zwischen 0,0 und 1,0 und entspricht dem Wert, der in der benutzerdefinierten Funktion „ MAIN “ festgelegt wurde. Dieser Wert ist nützlich für die Berechnung von Fresnel-Beiträgen, wenn der von „ FRESNEL_CONTRIB “ bereitgestellte integrierte Fresnel-Beitrag nicht verwendet wird.

  void SPECULAR_LIGHT()
  {
      vec3 H = normalize(VIEW_VECTOR + TO_LIGHT_DIR);
      float cosAlpha = max(0.0, dot(H, normalize(NORMAL)));
      float shine = pow(cosAlpha, exp2(15.0 * (1.0 - ROUGHNESS) + 1.0) * 0.25);
      SPECULAR += shine * LIGHT_COLOR * FRESNEL_CONTRIB * SHADOW_CONTRIB * LIGHT_ATTENUATION;
  }

• void POST_PROCESS() Sofern vorhanden, wird diese Funktion am Ende der Fragment-Pipeline aufgerufen. Die Aufgabe der Funktion besteht darin, „ COLOR_SUM “ mit den endgültigen diffusen, spiegelnden und emittierenden Termen abzuschließen. Im Gegensatz zu „ FRAGCOLOR “ für ein nicht schattiertes Material wird „ COLOR_SUM “ automatisch einem Tonemapping unterzogen, bevor es in den Framebuffer geschrieben wird. Zu Debugging-Zwecken ist es manchmal nützlich, einen Wert auszugeben, der nicht als Farbe behandelt werden soll. Um zu vermeiden, dass das Tonemapping diesen Wert verzerrt, kann es deaktiviert werden, indem die Eigenschaft „ tonemapMode “ auf

  „

  TonemapModeNone

  “

  gesetzt wird
  • .

  Die Funktion kann in die folgenden speziellen Variablen schreiben:

  • vec4 „ COLOR_SUM “ – die Ausgabe des Fragment-Shaders. Der Standardwert ist „vec4(DIFFUSE.rgb + SPECULAR + EMISSIVE, DIFFUSE.a)“

  Die Funktion kann die folgenden speziellen Variablen lesen.

  • vec4 DIFFUSE – Der endgültige Diffusanteil der Fragment-Pipeline.
  • vec3 SPECULAR – Der endgültige Spiegelungsanteil der Fragment-Pipeline.
  • vec3 EMISSIVE – Der endgültige Emissionsanteil der Fragment-Pipeline.
  • vec2 UV0 – Der erste Satz von Texturkoordinaten aus dem Vertex-Shader.
  • vec2 UV1 – Der zweite Satz von Texturkoordinaten aus dem Vertex-Shader.

  void POST_PROCESS()
  {
      float center_x = textureSize(SCREEN_TEXTURE, 0).x * 0.5;
      if (gl_FragCoord.x > center_x)
          COLOR_SUM = DIFFUSE;
      else
          COLOR_SUM = vec4(EMISSIVE, DIFFUSE.a);
  }

• void IBL_PROBE() Wenn vorhanden, wird diese Funktion für IBL (Image-Based Lighting) aufgerufen. Die Aufgabe der Funktion besteht darin, sowohl die diffusen als auch die spiegelnden Beiträge von IBL zu den beschreibbaren Spezialvariablen DIFFUSE und SPECULAR hinzuzufügen.

  Die Funktion kann in die folgenden Spezialvariablen schreiben:

  • vec3 DIFFUSE Sammelt die diffusen Lichtanteile pro Fragment.
  • vec3 SPECULAR Sammelt die spiegelnden Lichtanteile pro Fragment.

  Die Funktion kann die folgenden Spezialvariablen lesen.

  • vec4 BASE_COLOR Die Grundfarbe und der Material-Alpha-Wert.
  • float AO_FACTOR Der Okklusionsfaktor im Bildschirmraum.
  • float SPECULAR_AMOUNT Der Spiegelungsgrad.
  • float ROUGHNESS Der abschließende Emissionsterm der Fragment-Pipeline.
  • vec3 NORMAL Der Normalenvektor im Weltraum.
  • vec3 VIEW_VECTOR Zeigt in Richtung der Kamera.
  • mat3 IBL_ORIENTATION Die Ausrichtung der Lichtprobe. Sie stammt aus SceneEnvironment::probeOrientation.

  void IBL_PROBE()
  {
      vec3 smpDir = IBL_ORIENTATION * NORMAL;
      DIFFUSE += AO_FACTOR * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, smpDir, IBL_MAXMIPMAP).rgb;
  }

Benutzerdefinierte Variablen zwischen Funktionen

Zusätzliche Variablen können von der MAIN-Funktion an die anderen Funktionen übergeben werden. Das Schlüsselwort „ SHARED_VARS “ kann zur Definition neuer benutzerdefinierter Variablen verwendet werden. Auf diese benutzerdefinierten Variablen kann mit „SHARED.<Variablenname>“ zugegriffen werden.

Beispielsweise kann ein schattiertes benutzerdefiniertes Material einen gemeinsam genutzten Wert aus der MAIN-Funktion abrufen und diesen in anderen Funktionen verwenden.

SHARED_VARS {
    vec3 colorThreshold;
};
void MAIN()
{
    BASE_COLOR = texture(baseColorMap, UV0);
    SHARED.colorThreshold = texture(thresholdMap, UV0).rgb;
}
void DIRECTIONAL_LIGHT()
{
    if (DIFFUSE >= SHARED.colorThreshold) {
        DIFFUSE = SHARED.colorThreshold;
        return;
    }
    DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB;
}

SHARED_VARS {
    float sheenIntensity;
    float sheenRoughness;
    vec3 sheenColor;
    vec3 outSheenColor;
};
void MAIN()
{
    ...
    vec4 tex = texture(uSheenMap, UV0);
    SHARED.sheenColor = tex.rgb;
    SHARED.sheenIntensity = tex.a;
    SHARED.sheenRoughness = uSheenRoughness;
    SHARED.outSheenColor = vec3(0.0);
}
void SPECULAR_LIGHT()
{
    SHARED.outSheenColor += ...;
}
void POST_PROCESS()
{
    COLOR_SUM = DIFFUSE + SPECULAR + EMISSIVE + SHARED.outSheenColor;
}

Weitere spezielle Schlüsselwörter

Der benutzerdefinierte Fragment-Shader-Code kann frei auf Uniforms (wie z. B. „ CAMERA_DIRECTION “ oder „ CAMERA_POSITION “) sowie auf Varyings zugreifen, die vom benutzerdefinierten Vertex-Shader übergeben werden. Zusätzlich stehen eine Reihe von integrierten Varyings als spezielle Schlüsselwörter zur Verfügung. Einige davon sind insofern optional, als ein Vertex- MAIN diese selbst berechnen und weitergeben könnte; um jedoch Datenduplikate zu vermeiden, können Fragment- stattdessen auch auf diese integrierten Variablen zurückgreifen. Diese integrierten Variablen stehen in Light-Prozessor-Funktionen und im Fragment-MAIN zur Verfügung.

• vec3 VAR_WORLD_NORMAL – Interpolierte Normale, transformiert durch NORMAL_MATRIX.
• vec3 VAR_WORLD_TANGENT – Interpolierte Tangente, transformiert durch MODEL_MATRIX.
• vec3 VAR_WORLD_BINORMAL – Interpolierte Binormale, transformiert durch MODEL_MATRIX
• vec3 NORMAL – Im Gegensatz zu VAR_WORLD_NORMAL, bei dem es sich um die interpolierte Normale in ihrer ursprünglichen Form handelt, wird dieser Wert möglicherweise an die beidseitige Darstellung angepasst: Beim Rendern mit deaktiviertem Culling wird die Normale bei Bedarf invertiert. Daher wird empfohlen, bei Beleuchtungs- und anderen Berechnungen NORMAL anstelle von VAR_WORLD_NORMAL zu verwenden, um in allen Culling-Modi korrekt zu funktionieren.
• vec3 TANGENT – Wie bei NORMAL wird dieser Wert möglicherweise hinsichtlich der beidseitigen Darstellung angepasst: Beim Rendern mit deaktiviertem Culling wird die Tangente bei Bedarf umgekehrt.
• vec3 BINORMAL – Wie bei NORMAL wird dieser Wert möglicherweise an die beidseitige Darstellung angepasst: Beim Rendern mit deaktiviertem Culling wird die Binormale bei Bedarf invertiert.
• vec3 VAR_WORLD_POSITION – Interpolierte Vertexposition im Weltraum ((MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz)
• vec4 VAR_COLOR – Die interpolierte Scheitelpunktfarbe, wenn Farben im Mesh bereitgestellt werden. Andernfalls vec4(1.0).
• vec3 VIEW_VECTOR – Zeigt in Richtung der Kamera. Dies entspricht im Wesentlichen dem normalisierten CAMERA_POSITION - VAR_WORLD_POSITION -Vektor.
• vec4 FRAGCOORD – Enthält die fensterrelativen Koordinaten des aktuellen Fragments.
• float FRAMEBUFFER_Y_UP – Der Wert ist 1, wenn die Y-Achse im Koordinatensystem für Framebuffer (Texturen) nach oben zeigt, d. h. (0, 0) ist die linke untere Ecke. Der Wert ist -1, wenn die Y-Achse nach unten zeigt, wobei (0, 0) die linke obere Ecke ist. Solche Unterschiede in den zugrunde liegenden Grafik-APIs spielen für die meisten benutzerdefinierten Materialien keine Rolle. Eine bemerkenswerte Ausnahme ist das Abtasten von „ SCREEN_TEXTURE “ mit Texturkoordinaten, die nicht auf „ FRAGCOORD “ basieren. Da die Ausrichtung von „ SCREEN_TEXTURE “ naturgemäß an die zugrunde liegende Grafik-API gebunden ist, kann die Verwendung von Texturkoordinaten aus einem Mesh entsprechende Anpassungen der Y-Koordinate erfordern.

  Beispielsweise zeigt der folgende Fragment-Shader, der für „Rectangle“- oder „Cube“-Meshes geeignet ist, die undurchsichtigen Objekte aus der Szene auf dem Modell an:

  VARYING vec2 texcoord;
  void MAIN()
  {
      vec2 screencoord = texcoord;
      if (FRAMEBUFFER_Y_UP < 0.0) // effectively: if not OpenGL
          screencoord.y = 1.0 - screencoord.y;
      BASE_COLOR = texture(SCREEN_TEXTURE, screencoord);
  }

  Beim Abtasten anderer Texturen als „ SCREEN_TEXTURE “ und „ DEPTH_TEXTURE “ oder wenn „ FRAGCOORD “ zur Berechnung der Texturkoordinate verwendet wird (was der typische Anwendungsfall für den Zugriff auf die Bildschirm- und Tiefentexturen wäre), ist eine solche Anpassung nicht erforderlich.

• float NDC_Y_UP – Der Wert ist 1, wenn die Y-Achse im normalisierten Gerätekoordinatensystem nach oben zeigt, und -1, wenn die Y-Achse nach unten zeigt. Eine nach unten zeigende Y-Achse tritt auf, wenn das Rendering mit Vulkan erfolgt. Für die meisten Materialien spielt dies keine Rolle, doch die Möglichkeit, basierend darauf eine Verzweigung vorzunehmen, kann in bestimmten fortgeschrittenen Anwendungsfällen nützlich sein.
• float NEAR_CLIP_VALUE – Der Wert lautet „ -1 “, wenn der Bereich der Clipping-Ebenen bei „ -1 “ beginnt und bis „ 1 “ reicht. Dies trifft zu, wenn OpenGL für das Rendering verwendet wird. Bei anderen Rendering-Backends lautet der Wert dieser Eigenschaft „ 0 “, was bedeutet, dass der Bereich der Clipping-Ebenen von „ 0 “ bis „ 1 “ reicht. Dieser Wert ist bei bestimmten Techniken nützlich, die den DEPTH_TEXTURE

  Beispielsweise veranschaulicht der folgende Fragment-Shader eine Technik zur Rekonstruktion der Position eines Werts aus dem Tiefenpuffer, um den Abstand zur aktuell gerenderten Position zu bestimmen. Bei Verwendung in Kombination mit „ INVERSE_PROJECTION_MATRIX “ muss der Tiefenwert in normalisierten Gerätekordinaten vorliegen; daher ist es wichtig, sicherzustellen, dass der Bereich des Tiefenwerts dies widerspiegelt. Wenn der „ NEAR_CLIP_VALUE “ auf „ -1 “ gesetzt ist, wird der Tiefenwert so skaliert, dass er zwischen -1 und 1 liegt.

  void MAIN() {
      vec2 screen_uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
      float depth = texture(DEPTH_TEXTURE, screen_uv).r;
  
      if (NEAR_CLIP_VALUE < 0.0) // effectively: if opengl
          depth = depth * 2.0 - 1.0;
  
      vec4 unproject = INVERSE_PROJECTION_MATRIX * vec4(screen_uv, depth, 1.0);
      depth = (unproject.xyz / unproject.w).z;
      float viewVectorZ = (VIEW_MATRIX * vec4(VAR_WORLD_POSITION, 1.0)).z;
      depth = viewVectorZ - depth;
  
      BASE_COLOR = vec4(depth, depth, depth, 1.0);
  }

• float IBL_EXPOSE – Die von der Lichtsonde emittierte Lichtmenge. Sie wird aus SceneEnvironment::probeExposure berechnet.

  DIFFUSE += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;

• float IBL_HORIZON – Der horizontale Abschneidewert für Reflexionen aus der unteren Hälfte der Umgebung. Er stammt aus Horizon Cut-Off, wird jedoch auf [-1, 0) umgemappt.

  vec3 diffuse += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
  if (IBL_HORIZON > -1.0) {
      float ctr = 0.5 + 0.5 * IBL_HORIZON;
      float vertWt = smoothstep(ctr * 0.25, ctr + 0.25, NORMAL.y);
      float wtScaled = mix(1.0, vertWt, IBL_HORIZON + 1.0);
      diffuse *= wtScaled;
  }

• float IBL_MAXMIPMAP – Die maximale Mipmap-Stufe von IBL_TEXTURE.

Instanziierung

Beim instanzierten Rendering gelten einige der oben genannten Schlüsselwörter nicht. Die folgenden Schlüsselwörter sind nur bei der Instanzierung verfügbar:

• INSTANCE_MODEL_MATRIX -> mat4, Ersatz für „ MODEL_MATRIX “, einschließlich der Instanzierungstransformation.
• INSTANCE_MODELVIEWPROJECTION_MATRIX -> mat4, Ersatz für „ MODELVIEWPROJECTION_MATRIX “, einschließlich der Instanzierungstransformation.
• INSTANCE_COLOR -> vec4, die Instanzfarbe: muss mit „ COLOR “ kombiniert werden.
• INSTANCE_DATA -> vec4, benutzerdefinierte Instanzdaten.
• INSTANCE_INDEX -> int, die Instanznummer und der Index in der Instanzierungstabelle.

Bildschirm-, Tiefen- und andere Texturen

Die Rendering-Pipeline kann den benutzerdefinierten Material-Shadern eine Reihe von Texturen mit Inhalten aus speziellen Render-Durchläufen zur Verfügung stellen. Dies gilt sowohl für schattierte als auch für unschattierte benutzerdefinierte Materialien.

Beispielsweise möchte ein Shader möglicherweise auf eine Tiefentextur zugreifen, die den Inhalt des Tiefenpuffers für die opaken Objekte in der Szene enthält. Dies wird durch das Abtasten von ` DEPTH_TEXTURE` erreicht. Eine solche Textur wird normalerweise nicht generiert, es sei denn, es besteht ein tatsächlicher Bedarf dafür. Daher fungiert das Vorhandensein der folgenden Schlüsselwörter im Vertex- oder Fragment-Shader auch als Schalter, um die – potenziell rechenintensiven – Durchläufe zur Erzeugung der betreffenden Textur zu aktivieren. (Natürlich könnte es sein, dass einige davon aufgrund anderer Einstellungen bereits aktiviert sind, wie beispielsweise durch die Ambient-Occlusion-Parameter unter SceneEnvironment oder durch einen Post-Processing-Effekt, der auf der Tiefentextur basiert; in diesem Fall werden die betreffenden Texturen unabhängig vom benutzerdefinierten Material generiert, sodass das Abtasten dieser speziellen Texturen im Material außer dem Texturzugriff selbst keine zusätzlichen Kosten verursacht)

• SCREEN_TEXTURE - Falls vorhanden, wird dem Shader unter diesem Namen eine Textur (sampler2D oder sampler2DArray) mit dem Farbpuffer aus einem Rendering-Durchgang bereitgestellt, der den Inhalt der Szene enthält, wobei transparente Materialien sowie Materialien, die ebenfalls die SCREEN_TEXTURE verwenden, ausgeschlossen sind. Die Textur kann für Techniken verwendet werden, die den Inhalt des Framebuffers benötigen, in den gerendert wird. Die Textur „SCREEN_TEXTURE“ verwendet denselben Clear-Modus wie „ View3D “. Die Größe dieser Texturen entspricht in Pixeln der Größe des „ View3D “. Ein Fragment-Shader könnte beispielsweise Folgendes enthalten: `

  vec2 uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
  vec2 displace = vec2(0.1);
  vec4 c = texture(SCREEN_TEXTURE, uv + displace);

  `

  Beachten Sie, dass die Verwendung von ` SCREEN_TEXTURE ` eine angemessene und bewusste Gestaltung der Szene erfordert. Objekte, die solche Materialien verwenden, müssen sorgfältig positioniert werden, in der Regel über allen anderen Objekten, die in der Textur sichtbar sein sollen. Objekte, die in irgendeiner Form Halbtransparenz verwenden, sind niemals Teil des „ SCREEN_TEXTURE “. Häufig wird „ SCREEN_TEXTURE “ in Kombination mit „ BASE_COLOR “ im „ MAIN “ verwendet. Der folgende benutzerdefinierte Fragment-Shader wendet beispielsweise einen Emboss-Effekt an, während Fragmente, die nicht von opaken Objekten berührt werden, transparent bleiben. Dies setzt voraus, dass das Objekt mit dem Material im Vordergrund platziert ist und dass das Blending aktiviert ist.

  void MAIN()
  {
      vec2 size = vec2(textureSize(SCREEN_TEXTURE, 0));
      vec2 uv = FRAGCOORD.xy / size;
  
      // basic emboss effect
      vec2 d = vec2(1.0 / size.x, 1.0 / size.y);
      vec4 diff = texture(SCREEN_TEXTURE, uv + d) - texture(SCREEN_TEXTURE, uv - d);
      float c = (diff.x + diff.y + diff.z) + 0.5;
  
      float alpha = texture(SCREEN_TEXTURE, uv).a;
      BASE_COLOR = vec4(vec3(c), alpha);
  }

  Beim Multiview-Rendering ist „ SCREEN_TEXTURE “ ein „ sampler2DArray “. Verwenden Sie „ VIEW_INDEX “, um die zu verwendende Ebene auszuwählen. Für VR-/AR-Anwendungen, die beide Rendering-Arten unterstützen sollen, lautet der portable Ansatz wie folgt:

  #if QSHADER_VIEW_COUNT >= 2
      vec4 c = texture(SCREEN_TEXTURE, vec3(uv, VIEW_INDEX));
  #else
      vec4 c = texture(SCREEN_TEXTURE, uv);
  #endif

• SCREEN_MIP_TEXTURE – In den meisten Punkten identisch mit „ SCREEN_TEXTURE “, mit dem Unterschied, dass für diese Textur Mipmaps generiert werden. Dies kann je nach Bildschirmgröße und aufgrund der Notwendigkeit, die Mipmaps bei jedem Rendern der Szene neu zu generieren, eine leistungsintensive Funktion sein. Verwenden Sie daher grundsätzlich „ SCREEN_TEXTURE “, es sei denn, das benutzerdefinierte Material implementiert eine Technik, die auf den Mip-Ebenen der Textur basiert (z. B. die Verwendung von „ textureLod “ im Shader).
• DEPTH_TEXTURE - Falls vorhanden, wird dem Shader unter diesem Namen eine Textur (sampler2D oder sampler2DArray) mit dem (nicht linearisierten) Inhalt des Tiefenpuffers zur Verfügung gestellt. Es werden nur undurchsichtige Objekte einbezogen. Ein Fragment-Shader könnte beispielsweise Folgendes enthalten:

  ivec2 dtSize = textureSize(DEPTH_TEXTURE, 0);
  vec2 dtUV = (FRAGCOORD.xy) / vec2(dtSize);
  vec4 depthSample = texture(DEPTH_TEXTURE, dtUV);
  float zNear = CAMERA_PROPERTIES.x;
  float zFar = CAMERA_PROPERTIES.y;
  float zRange = zFar - zNear;
  float z_n = 2.0 * depthSample.r - 1.0;
  float d = 2.0 * zNear * zFar / (zFar + zNear - z_n * zRange);
  d /= zFar;

  Beim Multiview-Rendering ist DEPTH_TEXTURE ein „ sampler2DArray “. Verwenden Sie VIEW_INDEX, um die zu verwendende Ebene auszuwählen. Für VR/AR-Anwendungen, die beide Rendering-Arten unterstützen sollen, lautet der portable Ansatz wie folgt:

  #if QSHADER_VIEW_COUNT >= 2
      vec4 depthSample = texture(DEPTH_TEXTURE, vec3(uv, VIEW_INDEX));
  #else
      vec4 depthSample = texture(DEPTH_TEXTURE, uv);
  #endif

• NORMAL_ROUGHNESS_TEXTURE – Falls vorhanden, wird dem Shader unter diesem Namen eine Textur (sampler2D) mit den Welt-Raum-Normalen und der Materialrauheit bereitgestellt. Es werden nur undurchsichtige Objekte berücksichtigt. Die Rauheit wird im Alphakanal gespeichert. Ein Fragment-Shader könnte beispielsweise Folgendes enthalten:

  vec3 N = normalize(texture(NORMAL_ROUGHNESS_TEXTURE, uv).rgb);

• AO_TEXTURE – Sofern vorhanden und Screen-Space-Ambient-Occlusion in SceneEnvironment aktiviert ist (d. h., wenn sowohl die AO-Stärke als auch die Entfernung ungleich Null sind), wird die SSAO-Textur (sampler2D oder sampler2DArray) dem Shader unter diesem Namen zur Verfügung gestellt. Das Abtasten dieser Textur kann bei unschattierten Materialien nützlich sein. Schattierte Materialien verfügen über eine integrierte Unterstützung für Ambient Occlusion. Das bedeutet, dass der Ambient-Occlusion-Faktor automatisch berücksichtigt wird. In einem Fragment-Shader für ein unschattiertes Material könnte man hingegen Folgendes schreiben, um dasselbe zu erreichen:

  ivec2 aoSize = textureSize(AO_TEXTURE, 0);
  vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
  float aoFactor = texture(AO_TEXTURE, aoUV).x;

  Beim Multiview-Rendering ist „ AO_TEXTURE “ ein „ sampler2DArray “. Verwenden Sie „ VIEW_INDEX “, um die zu verwendende Ebene auszuwählen. Für VR-/AR-Anwendungen, die beide Rendering-Arten unterstützen sollen, lautet der portable Ansatz wie folgt:

  #if QSHADER_VIEW_COUNT >= 2
      ivec2 aoSize = textureSize(AO_TEXTURE, 0).xy;
      vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
      float aoFactor = texture(AO_TEXTURE, vec3(aoUV, VIEW_INDEX)).x;
  #else
      ivec2 aoSize = textureSize(AO_TEXTURE, 0);
      vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
      float aoFactor = texture(AO_TEXTURE, aoUV).x;
  #endif

• IBL_TEXTURE - Es wird kein spezieller Rendering-Durchgang aktiviert, aber die Funktion kann verwendet werden, wenn das Material „ Material::lightProbe “ enthält oder das Modell im Geltungsbereich von „ SceneEnvironment::lightProbe “ liegt.

  void IBL_PROBE()
  {
      DIFFUSE += AO_FACTOR * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
  }

• MOTION_VECTOR_TEXTURE — Aktiviert einen dedizierten Rendering-Durchlauf, der Bewegungsvektoren pro Objekt für die Szene berechnet. Die Ausgabe ist eine Vierkanal-Textur: Die R- und G-Komponenten enthalten die skalierten Bewegungsvektoren der Modelle, während die B- und A-Komponenten die unskalierten Bewegungsvektoren speichern.
• VIEW_INDEX - Bei Verwendung im benutzerdefinierten Shader-Code handelt es sich hierbei um eine (nicht interpolierte) `uint`-Variable. Wenn kein Multiview-Rendering verwendet wird, ist der Wert immer 0. Bei Multiview-Rendering entspricht der Wert dem aktuellen Ansichtsindex (z. B. `gl_ViewIndex`). Besonders nützlich in Kombination mit „ DEPTH_TEXTURE “ und ähnlichen Funktionen, wenn das Multiview-Rendering aktiviert ist.

Siehe auch „ SceneEnvironment::tonemapMode“ , „Using Image-Based Lighting“, „Qt Quick 3D – Beispiel für benutzerdefinierte Shader“, „Qt Quick 3D – Beispiel für benutzerdefinierte Materialien“ sowie „Programmierbare Materialien, Effekte, Geometrie und Texturdaten“.

Dokumentation zu den Eigenschaften

alwaysDirty : bool

Gibt an, dass der Materialstatus immer „schmutzig“ ist, was bedeutet, dass das Material bei jeder Verwendung durch den „ QtQuick3D “ aktualisiert werden muss.

destinationAlphaBlend : enumeration [since 6.7]

Legt den Ziel-Alpha-Blend-Faktor fest. Der Standardwert ist „ CustomMaterial.NoBlend “. Dieser Wert wird nur dann aktiv verwendet, wenn „ sourceBlend “ und „ destinationBlend “ auf einen vom Standard abweichenden Wert gesetzt sind.

Diese Eigenschaft wurde in Qt 6.7 eingeführt.

Siehe auch destinationBlend.

destinationBlend : enumeration

Legt den Ziel-Mischfaktor fest. Der Standardwert ist „ CustomMaterial.NoBlend “.

Siehe auch „ sourceBlend “.

fragmentShader : url

Gibt die Datei mit dem Ausschnitt des benutzerdefinierten Fragment-Shader-Codes an.

Der Wert ist eine URL und muss entweder eine lokale Datei sein oder das qrc-Schema verwenden, um auf Dateien zuzugreifen, die über das Qt-Ressourcensystem eingebettet sind. Relative Dateipfade (ohne Schema) werden ebenfalls akzeptiert; in diesem Fall wird die Datei als relativ zur Komponente (der Datei „ .qml “) behandelt.

Siehe auch „ vertexShader “.

lineWidth : real

Diese Eigenschaft bestimmt die Breite der gerenderten Linien, wenn die Geometrie den Primitivtyp „Linien“ oder „Linienstreifen“ verwendet. Der Standardwert ist 1,0. Diese Eigenschaft ist beim Rendern anderer Geometrietypen, wie beispielsweise Dreiecksnetze, nicht relevant.

shadingMode : enumeration

Gibt den Materialtyp an. Der Standardwert ist „Schattiert“.

sourceAlphaBlend : enumeration [since 6.7]

Legt den Alpha-Mischfaktor für die Quelle fest. Der Standardwert ist „ CustomMaterial.NoBlend “. Dieser Wert wird nur dann aktiv verwendet, wenn „ sourceBlend “ und „ destinationBlend “ auf einen vom Standard abweichenden Wert gesetzt sind.

Diese Eigenschaft wurde in Qt 6.7 eingeführt.

Siehe auch sourceBlend.

sourceBlend : enumeration

Legt den Mischfaktor für die Quelle fest. Der Standardwert lautet „ CustomMaterial.NoBlend “.

Siehe auch „ destinationBlend “.

vertexShader : url

Gibt die Datei mit dem Ausschnitt des benutzerdefinierten Vertex-Shader-Codes an.

Der Wert ist eine URL und muss entweder eine lokale Datei sein oder das qrc-Schema verwenden, um auf Dateien zuzugreifen, die über das Qt-Ressourcensystem eingebettet sind. Relative Dateipfade (ohne Schema) werden ebenfalls akzeptiert; in diesem Fall wird die Datei als relativ zur Komponente (die Datei „ .qml “) behandelt.

Siehe auch „ fragmentShader “.