QCanvasCustomBrush Class

Description détaillée

QCanvasCustomBrush est un pinceau de tracé/remplissage doté de shaders de sommets et/ou de fragments personnalisés.

Ces shaders doivent être écrits en GLSL de style Vulkan, à l’instar des shaders Qt Quick ShaderEffect . Ils doivent toujours contenir une instruction QC_INCLUDE, avec soit "customfrag.glsl", soit "customvert.glsl". Cela permet d’accéder à un bloc uniform, aux textures d’image et de police, ainsi qu’à quelques fonctions d’aide.

iTime Voici un exemple d’élément couramment utilisé dans le bloc « uniform » intégré. L’appel de ` setAnimationRunning()` avec ` true ` entraînera la mise à jour automatique de cette valeur à chaque image, ce qui peut être utilisé pour générer du contenu animé.

Entrées de shader intégrées, uniformes et fonctions d’aide

L’instruction QC_INCLUDE n’est pas une directive de préprocesseur standard. Elle est gérée par qt_add_custom_brush_shaders() lors de la compilation, avant que le shader ne soit transmis au pipeline de compilation de shaders habituel. Cette instruction est remplacée par un bloc de code source GLSL qui déclare les entrées et sorties du shader, les échantillonneurs de texture, un bloc d’uniformes partagés et, pour les shaders de fragments, un ensemble de fonctions d’aide. Utilisez ` "customvert.glsl" ` dans les shaders de sommets et ` "customfrag.glsl" ` dans les shaders de fragments.

Cela signifie qu’un shader de pinceau personnalisé ne déclare pas lui-même ces entrées, sorties, échantillonneurs ou uniformes ; ils sont tous mis à disposition par l’instruction ` QC_INCLUDE `.

Interface du shader de sommets

Un shader de sommets qui inclut « "customvert.glsl" » dispose des entrées et sorties suivantes :

• in vec2 vertex - La position du sommet dans le système de coordonnées du canevas.
• in vec2 tcoord - La coordonnée de texture associée au sommet.
• out vec2 texCoord - Transmis au shader de fragment. Généralement défini sur ` tcoord`.
• out vec2 fragCoord - Transmis au shader de fragment. Généralement défini sur ` vertex`.

De plus, les uniformes suivants, liés à la transformation, sont disponibles :

• vec4 viewRect - Le rectangle de la fenêtre d’affichage, sous la forme (x, y, largeur, hauteur).
• int ndcIsYDown - Différent de zéro lorsque l’axe Y du système de coordonnées normalisé du périphérique est orienté vers le bas, comme c’est le cas avec certaines API graphiques. Tenez-en compte lors du calcul de ` gl_Position`.
• mat3 vertMatrix - La matrice de transformation actuelle.

Un shader de sommets doit écrire l’ gl_Position, et est censé transmettre l’ texCoord et l’ fragCoord à l’étape des fragments.

Un shader de sommets type se présente comme suit :

#version 440

QC_INCLUDE "customvert.glsl"

void main()
{
    texCoord = tcoord;
    fragCoord = vertex;
    vec2 v = (vertMatrix * vec3(vertex, 1.0)).xy;
    if (ndcIsYDown != 0)
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           -1.0 + 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
    else
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           1.0 - 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
}

Interface du shader de fragment

Un shader de fragment qui inclut "customfrag.glsl" dispose des entrées et sorties suivantes :

• in vec2 texCoord - La coordonnée de texture interpolée.
• in vec2 fragCoord - La position du fragment interpolée, dans le même système de coordonnées que la géométrie. Généralement utilisée pour générer des effets procéduraux.
• out vec4 fragColor - La couleur du fragment résultant, que le shader doit écrire. La sortie attendue utilise un alpha pré-multiplié.

Deux échantillonneurs de texture sont disponibles :

• sampler2D tex - La texture d’image.
• sampler2D fontTex - La texture de police, contenant un champ de distance signé des glyphes. Pertinent lorsque le pinceau est utilisé pour remplir du texte.

Les constantes de commodité ` TAU ` (égale à 2 * pi) et ` SQRT2 ` sont également définies.

Uniformes communs

Les shaders de sommets et de fragments qui utilisent ` QC_INCLUDE ` ont accès à un bloc d’uniformes partagé. Les membres les plus couramment utilisés sont :

• float iTime - Une valeur temporelle, en secondes, mise à jour à chaque image tant que isAnimationRunning() est égal à true. Utilisez-la pour piloter des animations. Voir setAnimationRunning().
• vec4 data1, vec4 data2, vec4 data3, vec4 data4 - Données personnalisées mises à la disposition du shader. Définissez-les depuis C++ via setData1(), setData2(), setData3() et setData4().
• float globalAlpha - L'opacité globale actuelle du « painter ». Les shaders de fragment doivent normalement multiplier fragColor par cette valeur.
• vec4 colorEffects - Les paramètres d'effets de couleur actifs. Ils sont généralement appliqués via la fonction applyColorEffects() plutôt que d'être consultés directement.
• float fontAlphaMin, float fontAlphaMax - Les seuils du champ de distance signé utilisés lors de l’anticrénelage des glyphes.

Fonctions d'aide pour les shaders de fragment

L'en-tête du shader de fragment fournit les fonctions d'aide suivantes :

• float clipMask() - Renvoie la couverture de découpage (clip), dans l’intervalle [0, 1], pour le fragment actuel. Multipliez fragColor par cette valeur pour respecter le découpage du peintre.
• float antialiasingAlpha() - Renvoie la couverture d’anticrénelage, comprise entre 0 et 1, dérivée de texCoord. Multipliez fragColor par cette valeur pour obtenir des arêtes anticrénelées.
• float sdfFontAlphaRaw() - Renvoie la valeur brute du champ de distance signé échantillonnée à partir de ` fontTex ` à ` texCoord`, sans anticrénelage. Appliquez manuellement ` smoothstep() ` si nécessaire.
• float sdfFontAlpha() - Renvoie l’alpha du glyphe échantillonné à partir de fontTex à l’adresse texCoord, avec l’anticrénelage par défaut appliqué en fonction de fontAlphaMin et fontAlphaMax.
• void applyColorEffects(inout vec4 color) - Applique les effets actifs de contraste, de luminosité et de saturation à color sur place.

Un shader de fragment typique calcule fragColor, le multiplie par globalAlpha, le multiplie éventuellement par clipMask() et antialiasingAlpha() pour prendre en charge le clipping et l’anticrénelage, puis appelle enfin applyColorEffects().

Lorsque du texte est impliqué, il faut également tenir compte de sdfFontAlpha(). Par exemple :

#version 440

QC_INCLUDE "customfrag.glsl"

void main()
{
    float a = 0.6 + 0.2 * sin(0.1 * fragCoord.x + 4.0 * iTime);
    vec4 color = vec4(a, a, a, 1.0);
    fragColor = sdfFontAlpha() * globalAlpha * color;
    applyColorEffects(fragColor);
}

Ajout des shaders au projet

Les shaders utilisés avec QCanvasCustomBrush doivent toujours être ajoutés au projet d’application via la fonction CMake qt_add_custom_brush_shaders, fournie par le package Qt Canvas Painter. Cette fonction effectue un prétraitement supplémentaire au moment de la compilation avant d’invoquer en interne la fonction standard qt_add_shaders().

Par exemple :

qt_add_custom_brush_shaders(app "app_custombrush_shaders"
    PREFIX
        "/shaders"
    FILES
        brush1.frag
)

Utilisation du pinceau

Au moment de l’exécution, le fichier ` .qsb ` généré peut être utilisé, par exemple, comme suit :

QCanvasCustomBrush customBrush(":/shaders/brush1.frag.qsb"));
customBrush.setAnimationRunning(true); // iTime updates automatically
// expose custom data to the shader in data1
customBrush.setData1(QVector4D(1.0, 2.0, 3.0, 4.0));

Le `QCanvasCustomBrush` peut alors être utilisé dans un remplissage, par exemple :

painter->setFillStyle(customBrush);

Consultez qt_add_custom_brush_shaders pour plus de détails sur la fonction CMake, ainsi que la documentation du module Qt Shader Tools pour savoir comment travailler avec du code de shader multiplateforme dans Qt.