QSGRenderNode Class

Documentation des fonctions membres

[override virtual noexcept] QSGRenderNode::~QSGRenderNode()

Détruit le nœud de rendu. Les classes dérivées sont censées effectuer un nettoyage similaire à releaseResources() ici.

Avec QRhi et les ressources telles que QRhiBuffer, QRhiTexture, QRhiGraphicsPipeline, etc., c'est souvent une bonne pratique d'utiliser des pointeurs intelligents, tels que std::unique_ptr, qui peuvent souvent éviter la nécessité d'implémenter un destructeur, et conduire à un code source plus compact. Gardez à l'esprit, cependant, que l'implémentation de releaseResources(), contenant probablement un certain nombre d'appels reset() sur les unique_ptrs, est toujours importante.

Voir aussi releaseResources().

[virtual] QSGRenderNode::StateFlags QSGRenderNode::changedStates() const

Cette fonction doit renvoyer un masque où chaque bit représente les états graphiques modifiés par la fonction render().

L'implémentation par défaut renvoie 0, ce qui signifie qu'aucun état pertinent n'a été modifié dans render().

const QSGClipNode *QSGRenderNode::clipList() const

Renvoie la liste de clips actuelle.

[since 6.6] QRhiCommandBuffer *QSGRenderNode::commandBuffer() const

Renvoie le tampon de commande actuel.

Cette fonction a été introduite dans Qt 6.6.

Voir aussi renderTarget().

[virtual] QSGRenderNode::RenderingFlags QSGRenderNode::flags() const

Renvoie des indicateurs décrivant le comportement de ce nœud de rendu.

L'implémentation par défaut renvoie 0.

Voir aussi RenderingFlag et rect().

qreal QSGRenderNode::inheritedOpacity() const

Renvoie l'opacité effective actuelle.

const QMatrix4x4 *QSGRenderNode::matrix() const

Renvoie le pointeur sur la matrice de vue du modèle en cours.

[virtual, since 6.0] void QSGRenderNode::prepare()

Appelée à partir de la phase de préparation de la trame. Cette fonction est appelée avant chaque invocation de render().

Contrairement à render(), cette fonction est appelée avant que le scenegraph ne commence à enregistrer la passe de rendu pour la trame actuelle sur le tampon de commande sous-jacent. Ceci est utile lors du rendu avec des API graphiques, telles que Vulkan, où les opérations de type copie devront être enregistrées avant la passe de rendu.

L'implémentation par défaut est vide.

Lors de l'implémentation d'un QSGRenderNode qui utilise QRhi pour le rendu, interrogez l'objet QRhi à partir du QQuickWindow via QQuickWindow::rhi(). Pour obtenir un QRhiCommandBuffer auquel soumettre le travail, appelez commandBuffer(). Pour obtenir des informations sur la cible de rendu active, appelez renderTarget(). Voir l'exemple {Scene Graph - Custom QSGRenderNode} pour plus de détails.

Cette fonction a été introduite dans Qt 6.0.

[since 6.5] const QMatrix4x4 *QSGRenderNode::projectionMatrix() const

Renvoie le pointeur sur la matrice de projection actuelle.

Dans render(), il s'agit de la même matrice que celle renvoyée par RenderState::projectionMatrix(). Ce getter existe pour que prepare() ait aussi un moyen d'interroger la matrice de projection.

Lorsque l'on travaille avec une API graphique moderne, ou avec la couche d'abstraction graphique propre à Qt XML, il est plus que probable que l'on veuille charger *projectionMatrix() * *matrix() dans un tampon uniforme. C'est cependant quelque chose qui doit être fait dans prepare(), donc en dehors de l'enregistrement d'une passe de rendu. C'est pourquoi les deux matrices peuvent être interrogées directement à partir de QSGRenderNode, à la fois dans prepare() et render().

Cette fonction a été introduite dans Qt 6.5.

[virtual] QRectF QSGRenderNode::rect() const

Renvoie le rectangle de délimitation en coordonnées de l'élément pour la zone que render() touche. La valeur n'est utilisée que lorsque flags() inclut BoundedRectRendering, ignorée dans le cas contraire.

L'indication du rectangle en combinaison avec BoundedRectRendering est particulièrement importante avec le backend software car sinon, la présence d'un rendernode dans la scène déclencherait des mises à jour en plein écran, ce qui ignorerait toutes les optimisations de mises à jour partielles.

Pour les rendernodes couvrant toute la surface d'un QQuickItem correspondant, la valeur de retour sera (0, 0, item->width(), item->height()).

Voir aussi flags().

[virtual] void QSGRenderNode::releaseResources()

Cette fonction est appelée lorsque toutes les ressources graphiques personnalisées allouées par ce nœud doivent être libérées immédiatement. Si le nœud n'alloue pas directement des ressources graphiques (tampons, textures, cibles de rendu, clôtures, etc.) par l'intermédiaire de l'API graphique utilisée, il n'y a rien à faire ici.

Ne pas libérer toutes les ressources personnalisées peut conduire à un comportement incorrect dans les scénarios de perte de périphérique graphique sur certains systèmes, car la réinitialisation ultérieure du système graphique peut échouer.

Contrairement au destructeur, on s'attend à ce que render() puisse réinitialiser toutes les ressources dont il a besoin lorsqu'il est appelé après un appel à releaseResources().

Avec OpenGL, le contexte OpenGL de la scène sera courant à la fois lors de l'appel au destructeur et à cette fonction.

[pure virtual] void QSGRenderNode::render(const QSGRenderNode::RenderState *state)

Cette fonction est appelée par le moteur de rendu et doit peindre ce nœud en invoquant directement les commandes via QRhi ou directement via l'API graphique sous-jacente (OpenGL, Direct3D, etc.).

L'opacité effective peut être récupérée avec inheritedOpacity().

La matrice de projection est disponible via state, tandis que la matrice modèle-vue peut être récupérée via matrix(). La matrice combinée est alors la matrice de projection multipliée par la matrice modèle-vue. L'empilement correct des éléments de la scène est assuré par la matrice de projection.

Lors de l'utilisation des matrices fournies, le système de coordonnées pour les données de vertex suit les conventions habituelles de QQuickItem: le haut-gauche est (0, 0), le bas-droit est la largeur() et la hauteur() correspondantes de QQuickItem moins un. Par exemple, en supposant une disposition des coordonnées de chaque sommet sur deux flottants (x-y), un triangle couvrant la moitié de l'objet peut être spécifié comme suit : (largeur - 1, hauteur - 1), (0, 0), (0, hauteur - 1) dans le sens inverse des aiguilles d'une montre.

Les informations relatives à l'écrêtage sont calculées avant l'appel de la fonction. Les implémentations qui souhaitent prendre en compte l'écrêtage peuvent mettre en place un ciseau ou un pochoir sur la base des informations contenues dans state. La mémoire tampon du pochoir est remplie avec les formes de clip nécessaires, mais c'est à l'implémentation de permettre le test du pochoir.

Certains backends de scenegraph, les logiciels en particulier, n'utilisent pas de ciseaux ou de pochoir. Dans ce cas, la région du clip est fournie en tant que QRegion ordinaire.

Lors de l'implémentation d'un QSGRenderNode qui utilise QRhi pour le rendu, interrogez l'objet QRhi à partir du QQuickWindow via QQuickWindow::rhi(). Pour obtenir un QRhiCommandBuffer auquel soumettre le travail, appelez commandBuffer(). Pour obtenir des informations sur la cible de rendu active, appelez renderTarget(). Voir l'exemple {Scene Graph - Custom QSGRenderNode} pour plus de détails.

Avec Qt 6 et son moteur de rendu de graphe de scène basé sur QRhi, aucune hypothèse ne doit être faite sur l'état actif (OpenGL) lorsque cette fonction est appelée, même si OpenGL est en cours d'utilisation. Ne faites aucune supposition sur les pipelines et les états dynamiques liés à la liste de commandes/tampon lorsque cette fonction est appelée.

Avec certaines API graphiques, y compris lors de l'utilisation directe de QRhi, il peut être nécessaire de réimplémenter prepare() ou de se connecter au signal QQuickWindow::beforeRendering(). Ceux-ci sont appelés/émis avant d'enregistrer le début d'un renderpass sur le tampon de commande (vkCmdBeginRenderPass avec Vulkan, ou en commençant à encoder via MTLRenderCommandEncoder dans le cas de Metal. Les opérations de copie d'enregistrement ne peuvent pas être effectuées à l'intérieur de render() avec de telles API. Il faut plutôt effectuer ces opérations soit dans prepare(), soit dans le slot connecté à beforeRendering (avec DirectConnection).

Voir également QSGRendererInterface et QQuickWindow::rendererInterface().

[since 6.6] QRhiRenderTarget *QSGRenderNode::renderTarget() const

Renvoie la cible de rendu actuelle.

Ceci est fourni principalement pour permettre les implémentations de prepare() et render() qui utilisent QRhi en accédant aux renderPassDescriptor ou pixel size de QRhiRenderTarget.

Pour construire un QRhiGraphicsPipeline, ce qui implique de fournir un QRhiRenderPassDescriptor, demandez le renderPassDescriptor de la cible de rendu. Sachez toutefois que la cible de rendu peut changer au cours de la durée de vie de l'élément personnalisé QQuickItem et de l'élément QSGRenderNode. Par exemple, considérez ce qui se passe lorsque vous placez dynamiquement layer.enabled: true sur l'élément ou un de ses ancêtres : cela déclenche le rendu dans une texture, et non directement dans la fenêtre, ce qui signifie que l'élément QSGRenderNode va fonctionner avec une cible de rendu différente à partir de ce moment-là. La nouvelle cible de rendu peut alors avoir un format de pixel différent, ce qui peut rendre incompatibles des pipelines graphiques déjà construits. Ceci peut être géré avec une logique telle que la suivante :

if (m_pipeline && renderTarget()->renderPassDescriptor()->serializedFormat() != m_renderPassFormat) {
    delete m_pipeline;
    m_pipeline = nullptr;
}
if (!m_pipeline) {
    // Build a new QRhiGraphicsPipeline.
    // ...
    // Store the serialized format for fast and simple comparisons later on.
    m_renderPassFormat = renderTarget()->renderPassDescriptor()->serializedFormat();
}

Cette fonction a été introduite dans Qt 6.6.

Voir aussi commandBuffer().