QSGRenderNode Class

Documentation des fonctions membres

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

Supprime le nœud de rendu. Les classes dérivées doivent effectuer ici un nettoyage similaire à celui de la méthode releaseResources().

Avec QRhi et des ressources telles que QRhiBuffer, QRhiTexture, QRhiGraphicsPipeline, etc., il est souvent recommandé d’utiliser des pointeurs intelligents, tels que std::unique_ptr, ce qui permet souvent d’éviter d’avoir à implémenter un destructeur et d’obtenir un code source plus compact. Gardez toutefois à l’esprit qu’il reste important d’implémenter la fonction ` releaseResources()`, qui contiendra probablement plusieurs appels à `reset()` sur les `unique_ptrs`.

Voir également ` releaseResources()`.

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

Cette fonction doit renvoyer un masque dans lequel 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 des clips actuels.

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

Renvoie le tampon de commande actuel.

Cette fonction a été introduite dans Qt 6.6.

Voir également ` 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 également RenderingFlag et rect().

qreal QSGRenderNode::inheritedOpacity() const

Renvoie l'opacité effective actuelle.

const QMatrix4x4 *QSGRenderNode::matrix() const

Renvoie un pointeur vers la matrice modèle-vue actuelle.

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

Appelée lors de la phase de préparation de l'image. Cette fonction est appelée avant chaque invocation de ` render()`.

Contrairement à ` render()`, cette fonction est appelée avant que le graphe de scène ne commence à enregistrer le passage de rendu de l'image actuelle dans le tampon de commande sous-jacent. Cela s'avère utile lors du rendu avec des API graphiques, telles que Vulkan, où les opérations de type copie doivent être enregistrées avant le passage de rendu.

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

Lors de l’implémentation d’un ` QSGRenderNode ` utilisant l’ QRhi pour le rendu, interrogez l’objet ` QRhi ` à partir de l’ QQuickWindow via ` QQuickWindow::rhi()`. Pour obtenir un ` QRhiCommandBuffer ` vers lequel soumettre le travail, appelez ` commandBuffer()`. Pour interroger les informations concernant la cible de rendu active, appelez ` renderTarget()`. Consultez 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 un pointeur vers 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 afin que ` prepare()` dispose également d'un moyen d'interroger la matrice de projection.

Lorsque l’on utilise une API graphique moderne ou la couche d’abstraction graphique propre à Qt, il est très probable que l’on souhaite charger *projectionMatrix() * *matrix() dans un tampon uniforme. Cela doit toutefois être effectué dans prepare(), c’est-à-dire en dehors de l’enregistrement d’un passage de rendu. C’est pourquoi les deux matrices peuvent être interrogées directement à partir de l’ QSGRenderNode, tant dans ` prepare()` que dans ` render()`.

Cette fonction a été introduite dans Qt 6.5.

[virtual] QRectF QSGRenderNode::rect() const

Renvoie le rectangle englobant, exprimé en coordonnées de l’élément, de la zone touchée par la fonction ` render()`. Cette valeur n’est utilisée que lorsque la fonction ` flags()` inclut l’option ` BoundedRectRendering` ; dans le cas contraire, elle est ignorée.

Le rapport du rectangle en combinaison avec ` BoundedRectRendering ` est particulièrement important avec le backend ` software `, car sinon, la présence d'un nœud de rendu dans la scène déclencherait des mises à jour en plein écran, contournant ainsi toutes les optimisations de mise à jour partielle.

Pour les nœuds de rendu couvrant toute la surface d’un « QQuickItem » correspondant, la valeur renvoyée sera (0, 0, item->width(), item->height()).

Voir également 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 de ressources graphiques (tampons, textures, cibles de rendu, barrières, etc.) via l'API graphique utilisée, il n'y a rien à faire ici.

Le fait de ne pas libérer toutes les ressources personnalisées peut entraîner un comportement incorrect dans certains scénarios de perte du 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 elle a besoin lorsqu’elle est appelée après un appel à `releaseResources()`.

Avec OpenGL, le contexte OpenGL du graphe de scène sera actif aussi bien lors de l’appel du destructeur que lors de l’appel de cette fonction.

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

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

L'opacité effective peut être récupérée à l'aide de ` inheritedOpacity()`.

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

Lorsque l’on utilise les matrices fournies, le système de coordonnées des données de sommets suit les conventions habituelles de QQuickItem: le coin supérieur gauche est (0, 0), le coin inférieur droit correspond aux valeurs width() et height() de QQuickItem moins un. Par exemple, en supposant une disposition des coordonnées de deux flottants (x-y) par sommet, un triangle couvrant la moitié de l’élément peut être spécifié comme suit : (largeur - 1, hauteur - 1), (0, 0), (0, hauteur - 1), en utilisant le sens antihoraire.

Les informations de découpage sont calculées avant l’appel de la fonction. Les implémentations souhaitant prendre en compte le découpage peuvent mettre en place un « scissoring » ou un stencil en fonction des informations contenues dans state. Le tampon de stencil est rempli avec les formes de découpage nécessaires, mais il appartient à l’implémentation d’activer le test de stencil.

Certains backends de graphe de scène, notamment les logiciels, n’utilisent ni « scissoring » ni stencil. Dans ce cas, la région de découpage est fournie sous la forme d’un ` QRegion` ordinaire.

Lors de l’implémentation d’un ` QSGRenderNode ` utilisant le rendu par « QRhi », interrogez l’objet ` QRhi ` à partir de la ` QQuickWindow ` via ` QQuickWindow::rhi()`. Pour obtenir une ` QRhiCommandBuffer ` à laquelle soumettre le travail, appelez ` commandBuffer()`. Pour interroger les informations relatives à la cible de rendu active, appelez ` renderTarget()`. Reportez-vous à 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 formulée concernant l’état (OpenGL) actif lorsque cette fonction est appelée, même lorsque OpenGL est utilisé. Ne faites aucune supposition concernant les pipelines et les états dynamiques liés à la liste de commandes/au tampon de commandes lorsque cette fonction est appelée.

Avec certaines API graphiques, notamment lors de l’utilisation directe de ` QRhi `, il peut être nécessaire de réimplémenter également ` prepare()`, ou bien de se connecter au signal ` QQuickWindow::beforeRendering()`. Ces appels sont effectués/émis avant l’enregistrement du début d’un renderpass dans le tampon de commandes (vkCmdBeginRenderPass avec Vulkan, ou au moment de lancer l’encodage via MTLRenderCommandEncoder dans le cas de Metal). L’enregistrement des opérations de copie ne peut pas s’effectuer à l’intérieur de `render()` avec ces API. Effectuez plutôt 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.

Cette fonction est principalement fournie pour permettre aux implémentations de ` prepare()` et ` render()` qui utilisent ` QRhi ` d’accéder aux propriétés ` renderPassDescriptor ` ou ` pixel size` de l’objet ` QRhiRenderTarget`.

Pour créer une QRhiGraphicsPipeline, ce qui implique de fournir une QRhiRenderPassDescriptor, interrogez le renderPassDescriptor à partir de la cible de rendu. Sachez toutefois que la cible de rendu peut changer au cours du cycle de vie de l’ QQuickItem personnalisé et de l’ QSGRenderNode. Prenons par exemple ce qui se passe lorsque l’on définit dynamiquement layer.enabled: true sur l’élément ou l’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’ QSGRenderNode va désormais fonctionner avec une cible de rendu différente. La nouvelle cible de rendu peut alors présenter un format de pixel différent, ce qui peut rendre incompatibles les pipelines graphiques déjà mis en place. Ce problème peut être géré à l’aide d’une logique telle que celle-ci :

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 également commandBuffer().