QQuickRhiItemRenderer Class

Documentation des fonctions membres

QQuickRhiItemRenderer::QQuickRhiItemRenderer()

Crée un nouveau moteur de rendu.

Cette fonction est appelée sur le thread de rendu pendant la phase de synchronisation de l'arborescence de scène, lorsque le thread de l'interface graphique est bloqué.

Voir également QQuickRhiItem::createRenderer().

[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()

Le Renderer est automatiquement supprimé lors du nettoyage des ressources du graphe de scène associées à l'élément « QQuickRhiItem ».

Cette fonction est appelée sur le thread de rendu.

Dans certaines conditions, il est normal et prévisible que l’objet Renderer soit détruit puis recréé. En effet, la durée de vie du Renderer suit en réalité celle du nœud du graphe de scène sous-jacent. Par exemple, lorsque l’on modifie le parent d’un objet « QQuickRhiItem » afin qu’il appartienne à une autre « QQuickWindow », les nœuds du graphe de scène sont tous supprimés puis recréés en raison du changement de fenêtre. Cela implique également la suppression et la création d’un nouvel objet ` QQuickRhiItemRenderer`.

Contrairement à QRhiWidget, QQuickRhiItemRenderer n’a pas besoin d’implémenter de chemins de code supplémentaires pour libérer (ou libérer anticipativement) les ressources graphiques créées via QRhi. Il suffit de tout libérer dans le destructeur ou de s’appuyer sur des pointeurs intelligents.

[protected] QRhiTexture *QQuickRhiItemRenderer::colorTexture() const

Renvoie la texture servant de tampon de couleur pour l'élément.

Ne doit être appelée qu’à partir de ` initialize()` et ` render()`.

Contrairement au tampon de profondeur-stencil et à la fonction ` QRhiRenderTarget`, cette texture est toujours disponible et gérée par la fonction ` QQuickRhiItem`, quelle que soit la valeur de ` isAutoRenderTargetEnabled`.

Voir également msaaColorBuffer(), depthStencilBuffer(), renderTarget() et resolveTexture().

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::depthStencilBuffer() const

Renvoie le tampon de profondeur-stencil utilisé pour le rendu de l'élément.

Ne doit être appelé qu’à partir de ` initialize()` et ` render()`.

Disponible uniquement lorsque ` isAutoRenderTargetEnabled ` vaut ` true`. Dans le cas contraire, la valeur renvoyée est ` nullptr ` et il appartient à la réimplémentation de ` initialize()` de créer et de gérer un tampon de profondeur-stencil ainsi qu’un ` QRhiTextureRenderTarget`.

Voir également colorTexture() et renderTarget().

[pure virtual protected] void QQuickRhiItemRenderer::initialize(QRhiCommandBuffer *cb)

Appelée lors de la première initialisation de l'élément, lorsque la taille, le format ou le nombre d'échantillons de la texture associée changent, ou lorsque l'QRhi e ou la texture changent pour quelque raison que ce soit. La fonction doit gérer (créer si ce n'est pas encore fait, ajuster et reconstruire si la taille a changé) les ressources graphiques utilisées par le code de rendu dans render().

Pour interroger l’ QRhi, QRhiTexture et d’autres objets associés, appelez rhi(), colorTexture(), depthStencilBuffer() et renderTarget().

Lorsque la taille de l’élément change, l’objet QRhi, la texture du tampon de couleur et les objets du tampon de profondeur et du tampon de stencil sont tous les mêmes instances (les accesseurs renvoient donc les mêmes pointeurs) qu’auparavant, mais les tampons de couleur et de profondeur/stencil auront probablement été reconstruits, ce qui signifie que l’objet size et la ressource de texture native sous-jacente peuvent être différents de ceux de la dernière invocation.

Les réimplémentations doivent également tenir compte du fait que l’objet « QRhi » et la texture du tampon de couleur peuvent changer entre deux appels de cette fonction. Par exemple, lorsque l’élément est réaffecté à un nouvel « QQuickWindow », le « QRhi » et toutes les ressources associées gérées par le « QQuickRhiItem » seront des instances différentes de celles d’auparavant lors de l’appel suivant de cette fonction. Il est alors important que toutes les ressources « QRhi » existantes précédemment créées par la sous-classe soient détruites, car elles appartiennent à l’ancien « QRhi » qui ne doit plus être utilisé.

Lorsque ` isAutoRenderTargetEnabled ` est défini sur ` true` (valeur par défaut), un ` QRhiRenderBuffer ` de profondeur-stencil et un ` QRhiTextureRenderTarget ` associés à ` colorTexture()` (ou ` msaaColorBuffer()`) ainsi que le tampon de profondeur-stencil sont créés et gérés automatiquement. Les réimplémentations de `initialize()` et ` render()` peuvent interroger ces objets via ` depthStencilBuffer()` et ` renderTarget()`. Lorsque ` isAutoRenderTargetEnabled ` est défini sur ` false`, ces objets ne sont plus créés ni gérés automatiquement. Il appartiendra alors à l’implémentation de `initialize()` de créer les tampons et de configurer la cible de rendu comme elle le juge opportun. Lors de la gestion manuelle d’attachements de couleur ou de profondeur-stencil supplémentaires pour la cible de rendu, leur taille et leur nombre d’échantillons doivent toujours correspondre à ceux de ` colorTexture()` (ou ` msaaColorBuffer()`), faute de quoi des erreurs de rendu ou de validation de l’API 3D peuvent survenir.

Les ressources graphiques créées par la sous-classe doivent être libérées dans l’implémentation du destructeur de la sous-classe.

cb est l’ QRhiCommandBuffer e pour l’image en cours. La fonction est appelée lors de l’enregistrement d’une image, mais sans passe de rendu active. Le tampon de commande est principalement fourni pour permettre la mise en file d’attente d’ resource updates s sans passer par render().

Cette fonction est appelée sur le thread de rendu, s’il en existe un.

Voir également render().

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::msaaColorBuffer() const

Renvoie le tampon de rendu servant de tampon de couleur multi-échantillonnage pour l'élément.

Ne doit être appelé qu’à partir de ` initialize()` et ` render()`.

Lorsque sampleCount est supérieur à 1, et que l’anticrénelage multisample est donc activé, la fonction QRhiRenderBuffer renvoie un nombre d’échantillons correspondant et sert de tampon de couleur. Les pipelines graphiques utilisés pour effectuer le rendu dans ce tampon doivent être créés avec le même nombre d’échantillons, et le nombre d’échantillons du tampon de profondeur-stencil doit également correspondre. Le contenu multisample doit être résolu dans la texture renvoyée par la fonction ` resolveTexture()`. Lorsque ` isAutoRenderTargetEnabled ` est défini sur ` true`, la fonction ` renderTarget()` est automatiquement configurée pour effectuer cette opération, en définissant `msaaColorBuffer()` comme ` renderbuffer ` de l’attachement de couleur 0 et ` resolveTexture()` comme son ` resolveTexture`.

Lorsque le MSAA n’est pas utilisé, la valeur renvoyée est ` nullptr`. Utilisez alors ` colorTexture()` à la place.

Selon l’API graphique 3D sous-jacente, il se peut qu’il n’y ait aucune différence pratique entre les textures multi-échantillonnées et les tampons de rendu de couleur dont le nombre d’échantillons est supérieur à 1 (QRhi peut simplement mapper les deux au même type de ressource native). Certaines API plus anciennes peuvent toutefois faire la distinction entre les textures et les renderbuffers. Afin de prendre en charge OpenGL ES 3.0, où les renderbuffers multi-échantillons sont disponibles, mais pas les textures multi-échantillons, QQuickRhiItem effectue toujours le MSAA en utilisant une texture multi-échantillon QRhiRenderBuffer comme attachement de couleur (et jamais une texture multi-échantillon QRhiTexture).

Voir également colorTexture(), depthStencilBuffer(), renderTarget() et resolveTexture().

[pure virtual protected] void QQuickRhiItemRenderer::render(QRhiCommandBuffer *cb)

Appelée lorsque le contenu du tampon de couleur d'arrière-plan doit être mis à jour.

Il y a toujours au moins un appel à ` initialize()` avant que cette fonction ne soit appelée.

Pour demander des mises à jour, appelez ` QQuickItem::update()` lorsque vous effectuez l’appel depuis du code QML ou C++ sur le thread principal/GUI (par exemple, dans un setter de propriété), ou ` update()` lorsque vous effectuez l’appel depuis un callback ` QQuickRhiItemRenderer `. Appeler la fonction ` update()` de ` QQuickRhiItemRenderer` depuis `render()` entraînera le déclenchement continu de mises à jour.

cb est l’ QRhiCommandBuffer pour l’image en cours. La fonction est appelée alors qu’une image est en cours d’enregistrement, mais sans passe de rendu active.

Cette fonction est appelée sur le thread de rendu, s'il en existe un.

Voir également initialize() et synchronize().

[protected] QRhiRenderTarget *QQuickRhiItemRenderer::renderTarget() const

Renvoie l'objet cible de rendu qui doit être utilisé avec la fonction ` QRhiCommandBuffer::beginPass()` dans les réimplémentations de la fonction ` render()`.

Ne doit être appelé qu’à partir de ` initialize()` et ` render()`.

Disponible uniquement lorsque isAutoRenderTargetEnabled est true. Sinon, la valeur renvoyée est nullptr et il appartient à la réimplémentation de initialize() de créer et de gérer un tampon de profondeur-stencil et un QRhiTextureRenderTarget.

Lors de la création d’ graphics pipelines, un QRhiRenderPassDescriptor est nécessaire. Celui-ci peut être obtenu à partir de l’ QRhiTextureRenderTarget renvoyé en appelant renderPassDescriptor().

Voir également colorTexture(), depthStencilBuffer() et QQuickWindow::effectiveDevicePixelRatio().

[protected] QRhiTexture *QQuickRhiItemRenderer::resolveTexture() const

Renvoie la texture non multisample vers laquelle le contenu multisample est converti.

Le résultat est nullptr lorsque l’anticrénelage multisample n’est pas activé.

Ne doit être appelé qu'à partir de ` initialize()` et ` render()`.

Lorsque le MSAA est activé, il s’agit de la texture utilisée par le nœud du graphe de scène sous-jacent de l’élément lors de la texturation d’un quadrilatère dans le passage de rendu principal de ` Qt Quick`. Cependant, le rendu de ` QQuickRhiItemRenderer` doit cibler l’ QRhiRenderBuffer (multisample) renvoyée par ` msaaColorBuffer()`. Lorsque ` isAutoRenderTargetEnabled ` est défini sur ` true`, cela est pris en charge par l’ QRhiRenderTarget renvoyée par ` renderTarget()`. Sinon, il appartient au code de la sous-classe de configurer correctement un objet de destination de rendu avec à la fois le tampon de couleur et les textures de résolution.

Voir également la fonction ` colorTexture()`.

[protected] QRhi *QQuickRhiItemRenderer::rhi() const

Renvoie l'objet ` QRhi ` actuel.

Ne doit être appelé qu'à partir de ` initialize()` et ` render()`.

[pure virtual protected] void QQuickRhiItemRenderer::synchronize(QQuickRhiItem *item)

Cette fonction est appelée sur le thread de rendu, s'il existe, tandis que le thread principal/GUI est bloqué. Elle est appelée depuis the item's synchronize step, et permet de lire et d’écrire des données appartenant aux threads principal et de rendu. En règle générale, les valeurs de propriétés stockées dans ` QQuickRhiItem ` sont copiées dans ` QQuickRhiItemRenderer`, afin de pouvoir être lues en toute sécurité par la suite dans ` render()` lorsque les threads de rendu et principal continuent à fonctionner en parallèle.

Voir également initialize() et render().

[protected] void QQuickRhiItemRenderer::update()

Appelez cette fonction lorsque le contenu du tampon de couleur hors écran doit être mis à jour. (c'est-à-dire pour demander que la fonction render() soit appelée à nouveau ; cet appel aura lieu ultérieurement, et notez que les mises à jour sont généralement limitées à la fréquence d'affichage)

Cette fonction peut être appelée depuis ` render()` pour planifier une mise à jour.