ShaderEffect QML Type

Applique des ombres personnalisées à un rectangle. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

• blending : bool
• cullMode : enumeration
• fragmentShader : url
• log : string
• mesh : variant
• status : enumeration
• supportsAtlasTextures : bool (since QtQuick 2.4)
• vertexShader : url

Description détaillée

Le type ShaderEffect applique un shader personnalisé vertex et fragment (pixel) à un rectangle. Il permet d'ajouter des effets tels que l'ombre portée, le flou, la colorisation et le bouclage de page dans la scène QML.

Shaders

Dans Qt 5, les effets étaient fournis sous forme de code source GLSL (OpenGL Shading Language), souvent intégré sous forme de chaînes de caractères dans QML. À partir de Qt 5.8, il est également possible de faire référence à des fichiers, qu'ils soient locaux ou qu'ils se trouvent dans le système de ressources de Qt.

Dans Qt 6, Qt Quick prend en charge les API graphiques, telles que Vulkan, Metal et Direct3D 11. Par conséquent, il n'est plus possible de travailler avec des chaînes de source GLSL. Le nouveau pipeline de shaders est plutôt basé sur la compilation du code GLSL compatible avec Vulkan dans SPIR-V, suivie de la collecte d'informations de réflexion et de la traduction dans d'autres langages d'ombrage, tels que HLSL, le Metal Shading Language et diverses versions de GLSL. Les ressources résultantes sont rassemblées en un seul paquet, généralement stocké dans des fichiers portant l'extension .qsb. Ce processus est effectué hors ligne ou au plus tard au moment de la création de l'application. Au moment de l'exécution, le graphe de scène et l'abstraction graphique sous-jacente consomment ces fichiers .qsb. Par conséquent, ShaderEffect s'attend à des références de fichiers (locales ou qrc) dans Qt 6 à la place du code de nuanceur en ligne.

Les propriétés vertexShader et fragmentShader sont des URL dans Qt 6 et fonctionnent de manière très similaire à Image.source, par exemple. Cependant, seuls les schémas file et qrc sont pris en charge par ShaderEffect. Il est également possible d'omettre le schéma file, ce qui permet de spécifier un chemin relatif de manière pratique. Un tel chemin est résolu par rapport à l'emplacement du composant (le fichier .qml ).

Entrées et ressources du nuanceur

Il existe deux types d'entrées pour vertexShader: les uniformes et les vertex.

Les entrées suivantes sont prédéfinies :

• vec4 qt_Vertex avec la position 0 - position du vertex, le vertex en haut à gauche a la position (0, 0), le vertex en bas à droite (width, height).
• vec2 qt_MultiTexCoord0 avec l'emplacement 1 - coordonnées de texture, la coordonnée en haut à gauche est (0, 0), en bas à droite (1, 1). Si supportsAtlasTextures est vrai, les coordonnées seront basées sur la position dans l'atlas.

Les uniformes suivants sont prédéfinis :

• mat4 qt_Matrix - matrice de transformation combinée, le produit des matrices de l'élément racine à ce ShaderEffect, et une projection orthogonale.
• float qt_Opacity - opacité combinée, le produit des opacités de l'élément racine à ce ShaderEffect.

En outre, toute propriété pouvant être associée à un type GLSL peut être mise à la disposition des nuanceurs. La liste suivante montre comment les propriétés sont mappées :

• bool, int, qreal -> bool, int, float - Si le type dans le shader n'est pas le même que dans QML, la valeur est convertie automatiquement.
• QColor -> vec4 - Lorsque les couleurs sont transmises au shader, elles sont d'abord prémultipliées. Ainsi, Qt.rgba(0.2, 0.6, 1.0, 0.5) devient vec4(0.1, 0.3, 0.5, 0.5) dans le shader, par exemple.
• QRect, QRectF -> vec4 - Qt.rect(x, y, w, h) devient vec4(x, y, w, h) dans le shader.
• QPoint, QPointF, QSize, QSizeF -> vec2
• QVector3D -> vec3
• QVector4D -> vec4
• QTransform -> mat3
• QMatrix4x4 -> mat4
• QQuaternion -> vec4, la valeur scalaire est w.
• Image -> sampler2D - L'origine est dans le coin supérieur gauche et les valeurs de couleur sont prémultipliées. La texture est fournie telle quelle, à l'exclusion du fillMode de l'élément Image. Pour inclure le fillMode, utilisez ShaderEffectSource ou Image::layer::enabled.
• ShaderEffectSource -> sampler2D - L'origine se trouve dans le coin supérieur gauche et les valeurs de couleur sont prémultipliées.

Les échantillonneurs sont toujours déclarés comme des variables uniformes distinctes dans le code des nuanceurs. Les nuanceurs sont libres de choisir n'importe quel point de liaison pour ceux-ci, à l'exception de 0 qui est réservé au bloc uniforme.

Certains langages et API d'ombrage ont un concept d'objets image et échantillonneur séparés. Qt Quick fonctionne toujours avec des objets échantillonneur d'image combinés dans les nuanceurs, comme le supporte SPIR-V. Par conséquent, les nuanceurs fournis pour ShaderEffect doivent toujours utiliser des déclarations d'échantillonneur de type layout(binding = 1) uniform sampler2D tex;. La couche d'abstraction sous-jacente et le pipeline de shaders se chargent de faire fonctionner tout cela pour toutes les API et tous les langages d'ombrage pris en charge, de manière transparente pour les applications.

Le back-end du graphe de scène QML peut choisir d'allouer des textures dans des atlas de textures. Si une texture allouée dans un atlas est transmise à un ShaderEffect, elle est par défaut copiée à partir de l'atlas de textures dans une texture autonome, de sorte que les coordonnées de la texture s'étendent de 0 à 1, et que vous obteniez les modes d'enveloppement attendus. Cependant, cela augmente l'utilisation de la mémoire. Pour éviter la copie de la texture, définissez supportsAtlasTextures pour les shaders simples en utilisant qt_MultiTexCoord0, ou pour chaque "uniform sampler2D <nom>" déclarez un "uniform vec4 qt_SubRect_<nom>" qui se verra attribuer le rectangle source normalisé de la texture. Pour les textures autonomes, le rectangle source est [0, 1]x[0, 1]. Pour les textures contenues dans un atlas, le rectangle source correspond à la partie de l'atlas où la texture est stockée. La manière correcte de calculer les coordonnées d'une texture appelée "source" dans un atlas de textures est "qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0".

La sortie de fragmentShader doit être prémultipliée. Si blending est activé, le mélange source-surface est utilisé. Toutefois, il est possible d'obtenir un mélange additif en affichant zéro dans le canal alpha.

import QtQuick 2.0

Rectangle {
    width: 200; height: 100
    Row {
        Image { id: img;
                sourceSize { width: 100; height: 100 } source: "qt-logo.png" }
        ShaderEffect {
            width: 100; height: 100
            property variant src: img
            vertexShader: "myeffect.vert.qsb"
            fragmentShader: "myeffect.frag.qsb"
        }
    }
}

L'exemple suppose que myeffect.vert et myeffect.frag contiennent du code GLSL de style Vulkan, traité par l'outil qsb afin de générer les fichiers .qsb.

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb, vec3(0.344, 0.5, 0.156))), tex.a) * qt_Opacity;
}

Avoir un seul shader

Il n'est pas obligatoire de spécifier à la fois vertexShader et fragmentShader. De nombreuses implémentations de ShaderEffect voudront fournir un nuanceur de fragment uniquement dans la pratique, tout en s'appuyant sur le nuanceur de vertex intégré par défaut.

Le nuanceur de sommets par défaut transmet les coordonnées de la texture au nuanceur de fragments sous la forme de vec2 qt_TexCoord0 à l'emplacement 0.

Le fragment shader par défaut s'attend à ce que la coordonnée de texture soit transmise par le vertex shader sous la forme vec2 qt_TexCoord0 à l'emplacement 0, et il échantillonne à partir d'un sampler2D nommé source au point de liaison 1.

Couches ShaderEffect et Item

Le type ShaderEffect peut être combiné avec layered items.

Couche avec effet désactivé

Couche avec effet activé

Item { id: layerRoot layer.enabled: true layer.effect: ShaderEffect { fragmentShader: "effect.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D source; void main() { vec4 p = texture(source, qt_TexCoord0); float g = dot(p.xyz, vec3(0.344, 0.5, 0.156)); fragColor = vec4(g, g, g, p.a) * qt_Opacity; }

Il est également possible de combiner plusieurs éléments en couches :

Rectangle { id: gradientRect; width: 10 height: 10 gradient: Gradient { GradientStop { position: 0; color: "white" } GradientStop { position: 1; color: "steelblue" } } visible: false; // should not be visible on screen. layer.enabled: true; layer.smooth: true } Text { id: textItem font.pixelSize: 48 text: "Gradient Text" anchors.centerIn: parent layer.enabled: true // This item should be used as the 'mask' layer.samplerName: "maskSource" layer.effect: ShaderEffect { property var colorSource: gradientRect; fragmentShader: "mask.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D colorSource; layout(binding = 2) uniform sampler2D maskSource; void main() { fragColor = texture(colorSource, qt_TexCoord0) * texture(maskSource, qt_TexCoord0).a * qt_Opacity; }

Autres remarques

Par défaut, le ShaderEffect se compose de quatre sommets, un pour chaque coin. Pour les transformations de sommets non linéaires, telles que la courbure de page, vous pouvez spécifier une grille fine de sommets en spécifiant une résolution mesh.

Migration depuis Qt 5

Pour les applications Qt 5 avec des éléments ShaderEffect, la migration vers Qt 6 implique de

• Déplacer le code des shaders dans des fichiers distincts .vert et .frag,
• mettre à jour les shaders en GLSL compatible avec Vulkan,
• l'exécution de l'outil qsb sur ces fichiers,
• inclure les fichiers .qsb résultants dans l'exécutable avec le système de ressources Qt,
• et en référençant le fichier dans les propriétés vertexShader et fragmentShader.

Comme décrit dans le module Qt Shader Tools, certaines de ces étapes peuvent être automatisées en laissant CMake invoquer l'outil qsb au moment de la construction. Voir Qt Shader Tools Build System Integration pour plus d'informations et d'exemples.

Lorsqu'il s'agit de mettre à jour le code du shader, voici un aperçu des changements les plus courants.

attribute highp vec4 qt_Vertex;
attribute highp vec2 qt_MultiTexCoord0;
varying highp vec2 coord;
uniform highp mat4 qt_Matrix;
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

Le processus de conversion implique principalement la mise à jour du code pour être compatible avec GL_KHR_vulkan_glsl. Il convient de noter que Qt Quick utilise un sous-ensemble des fonctionnalités fournies par GLSL et Vulkan, et donc le processus de conversion pour les shaders ShaderEffect typiques est généralement simple.

• La directive version doit indiquer 440 ou 450, bien que la spécification d'une autre version de GLSL puisse également fonctionner, car l'extension GL_KHR_vulkan_glsl est écrite pour GLSL 140 et plus.
• Les entrées et les sorties doivent utiliser les mots-clés GLSL modernes in et out. En outre, il est nécessaire de spécifier un emplacement. Les espaces de noms des emplacements d'entrée et de sortie sont distincts, et l'attribution d'emplacements commençant par 0 pour les deux est donc sans danger.
• En ce qui concerne les entrées du vertex shader, les seules possibilités avec ShaderEffect sont l'emplacement 0 pour la position du vertex (traditionnellement appelé qt_Vertex) et l'emplacement 1 pour les coordonnées de la texture (traditionnellement appelé qt_MultiTexCoord0).
• Les sorties du nuanceur de sommets et les entrées du nuanceur de fragments sont définies par le code du nuanceur. Le nuanceur de fragment doit avoir une sortie vec4 à l'emplacement 0 (généralement appelé fragColor). Pour une portabilité maximale, les sorties de vertex et les entrées de fragment doivent utiliser le même numéro d'emplacement et le même nom. Lorsque l'on ne spécifie qu'un nuanceur de fragments, les coordonnées de texture sont transmises par le nuanceur de sommets intégré sous la forme vec2 qt_TexCoord0 à l'emplacement 0, comme le montrent les exemples ci-dessus.
• Les variables uniformes en dehors d'un bloc uniforme ne sont pas légales. Les données uniformes doivent être déclarées dans un bloc uniforme avec le point de liaison 0.
• Le bloc uniforme est censé utiliser le qualificatif std140.
• Au moment de l'exécution, le nuanceur de sommets et le nuanceur de fragments obtiendront le même tampon uniforme lié au point de liaison 0. Par conséquent, en règle générale, les déclarations du bloc uniforme doivent être identiques entre les nuanceurs. Cela concerne également les membres qui ne sont pas utilisés dans l'un des nuanceurs. Les noms des membres doivent correspondre, car avec certaines API graphiques, le bloc uniforme est converti en une structure uniforme traditionnelle, de manière transparente pour l'application.
• Lorsque vous ne fournissez qu'un seul des shaders, faites attention au fait que les shaders intégrés attendent qt_Matrix et qt_Opacity au sommet du bloc uniforme. (plus précisément, aux décalages 0 et 64, respectivement). En règle générale, il faut toujours les inclure en tant que premier et deuxième membres du bloc.
• Dans l'exemple, le bloc uniforme spécifie le nom du bloc buf. Ce nom peut être modifié librement, mais il doit correspondre à celui des nuanceurs. L'utilisation d'un nom d'instance, tel que layout(...) uniform buf { ... } instance_name;, est facultative. Lorsqu'il est spécifié, tous les accès aux membres doivent être qualifiés avec le nom de l'instance.

varying highp vec2 coord;
uniform lowp float qt_Opacity;
uniform sampler2D src;
void main() {
    lowp vec4 tex = texture2D(src, coord);
    gl_FragColor = vec4(vec3(dot(tex.rgb,
                        vec3(0.344, 0.5, 0.156))),
                             tex.a) * qt_Opacity;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb,
                     vec3(0.344, 0.5, 0.156))),
                          tex.a) * qt_Opacity;
}

• Les qualificateurs de précision (lowp, mediump, highp) ne sont pas utilisés actuellement.
• L'appel de fonctions GLSL intégrées doit respecter les noms GLSL modernes, notamment texture() au lieu de texture2D().
• Les échantillonneurs doivent utiliser des points de liaison à partir de 1.
• Lorsque Qt Quick effectue un rendu avec multiview activé, par exemple parce qu'il fait partie d'une scène 3D dont le rendu est effectué dans un environnement VR/AR où le contenu des yeux gauche et droit est généré en une seule passe, les shaders du ShaderEffect doivent être écrits en gardant cela à l'esprit. Avec un nombre de vues de 2 par exemple, il y aura 2 matrices (qt_Matrix est un tableau de mat4 avec deux éléments). Le vertex shader est censé prendre en compte gl_ViewIndex. Voir la section Multiview du manuel QSB pour des informations générales sur la création de shaders compatibles avec le multiview.

Voir aussi Item Layers, le manuel QSB, et Qt Shader Tools Build System Integration.

Documentation sur les propriétés

blending : bool

Si cette propriété est vraie, la sortie du site fragmentShader est mélangée à l'arrière-plan en utilisant le mode de fusion source-over. Si cette propriété est false, l'arrière-plan n'est pas pris en compte. Le mélange diminue les performances, c'est pourquoi il est préférable de définir cette propriété sur false lorsque le mélange n'est pas nécessaire. La valeur par défaut est true.

cullMode : enumeration

Cette propriété définit les côtés de l'élément qui doivent être visibles.

La valeur par défaut est NoCulling.

fragmentShader : url

Cette propriété contient une référence à un fichier contenant le paquetage de nuanceurs de fragments prétraités, généralement avec une extension de .qsb. La valeur est traitée comme un URL, de la même manière que d'autres types QML, tels que Image. Il doit s'agir d'un fichier local ou utiliser le schéma qrc pour accéder aux fichiers intégrés via le système de ressources Qt. L'URL peut être absolue ou relative à l'URL du composant.

Voir également vertexShader.

log : string [read-only]

Cette propriété contient un journal des avertissements et des erreurs de la dernière tentative de compilation des shaders. Elle est mise à jour en même temps que status est défini sur Compiled ou Error.

Voir également status.

mesh : variant

Cette propriété définit le maillage utilisé pour dessiner l'image ShaderEffect. Elle peut contenir n'importe quel objet GridMesh. Si une valeur de taille est attribuée à cette propriété, ShaderEffect utilise implicitement un GridMesh ayant la même valeur que mesh resolution. Par défaut, cette propriété est de taille 1x1.

Voir aussi GridMesh.

status : enumeration [read-only]

Cette propriété indique l'état actuel des shaders.

Lors de la définition du code source du fragment shader ou du vertex shader, le statut devient Uncompiled. La première fois que le site ShaderEffect est rendu avec un nouveau code source de shaders, les shaders sont compilés et liés, et le statut est mis à jour en Compilé ou Erreur.

Lorsque la compilation en cours d'exécution n'est pas utilisée et que les propriétés des shaders font référence à des fichiers contenant du bytecode, l'état est toujours Compilé. Le contenu du shader n'est examiné (hormis la réflexion de base pour découvrir les éléments d'entrée des vertex et les données du tampon constant) que plus tard dans le pipeline de rendu, de sorte que les erreurs potentielles (telles que les erreurs de disposition ou de signature de racine) ne seront détectées qu'à un stade ultérieur.

Voir également log.

supportsAtlasTextures : bool [since QtQuick 2.4]

Définissez cette propriété sur "true" pour confirmer que votre code de shader ne repose pas sur qt_MultiTexCoord0 allant de (0,0) à (1,1) par rapport au maillage. Dans ce cas, la plage de qt_MultiTexCoord0 sera plutôt basée sur la position de la texture dans l'atlas. Cette propriété n'a actuellement aucun effet s'il y a moins ou plus d'un uniforme d'échantillonneur utilisé en entrée de votre nuanceur.

Cela diffère de la fourniture d'uniformes qt_SubRect_<name> dans la mesure où ce dernier permet de dessiner une ou plusieurs textures de l'atlas dans un seul élément ShaderEffect, tandis que supportsAtlasTextures permet à plusieurs instances d'un composant ShaderEffect utilisant une image source différente de l'atlas d'être mis en lot dans un seul dessin. Les deux empêchent une texture d'être copiée hors de l'atlas lorsqu'elle est référencée par ShaderEffect.

La valeur par défaut est false.

Cette propriété a été introduite dans QtQuick 2.4.

vertexShader : url

Cette propriété contient une référence à un fichier contenant le paquet de vertex shaders prétraités, généralement avec une extension de .qsb. La valeur est traitée comme un URL, de la même manière que d'autres types QML, tels que Image. Il doit s'agir d'un fichier local ou utiliser le schéma qrc pour accéder aux fichiers intégrés via le système de ressources Qt. L'URL peut être absolue ou relative à l'URL du composant.

Voir également fragmentShader.