QQuickRhiItemRenderer Class

Documentation des fonctions membres

QQuickRhiItemRenderer::QQuickRhiItemRenderer()

Construit un nouveau moteur de rendu.

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

Voir aussi QQuickRhiItem::createRenderer().

[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()

Le moteur de rendu est automatiquement supprimé lorsque les ressources du graphe de scène pour l'élément QQuickRhiItem sont nettoyées.

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

Dans certaines conditions, il est normal et attendu que l'objet de rendu soit détruit puis recréé. En effet, la durée de vie du moteur de rendu suit le nœud du graphe de scène sous-jacent. Par exemple, lorsque l'on change le parent d'un objet QQuickRhiItem pour qu'il appartienne à un autre QQuickWindow, les nœuds du graphe de scène sont tous supprimés et 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 des chemins de code supplémentaires pour libérer (ou libérer de manière anticipée) 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é qu'à partir de initialize() et render().

Contrairement au tampon de profondeur et à QRhiRenderTarget, cette texture est toujours disponible et est gérée par QQuickRhiItem, indépendamment de la valeur de isAutoRenderTargetEnabled.

Voir aussi msaaColorBuffer(), depthStencilBuffer(), renderTarget() et resolveTexture().

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

Renvoie le tampon de profondeur utilisé par le rendu de l'élément.

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

Disponible uniquement si 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 et un QRhiTextureRenderTarget.

Voir également colorTexture() et renderTarget().

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

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

Pour interroger les objets QRhi, QRhiTexture et d'autres objets connexes, 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 du pochoir de profondeur sont tous les mêmes instances (les getters renvoient donc les mêmes pointeurs) qu'auparavant, mais les tampons de couleur et de profondeur/pochoir 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 être préparées au fait que l'objet QRhi et la texture du tampon de couleur peuvent changer entre les invocations de cette fonction. Par exemple, lorsque l'élément est réparti de manière à appartenir à un nouveau QQuickWindow, le QRhi et toutes les ressources connexes gérées par le QQuickRhiItem seront des instances différentes qu'auparavant lors de l'appel suivant à cette fonction. Il est alors important que toutes les ressources QRhi créées précédemment par la sous-classe soient détruites car elles appartiennent à l'ancien QRhi qui ne doit plus être utilisé.

Lorsque isAutoRenderTargetEnabled est true, ce qui est le cas par défaut, un crayon de profondeur QRhiRenderBuffer et un QRhiTextureRenderTarget associé au colorTexture() (ou msaaColorBuffer()) et au tampon du crayon de profondeur 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 remplacé par false, ces objets ne sont plus créés et gérés automatiquement. C'est plutôt à l'implémentation d'initialize() de créer des tampons et de configurer la cible de rendu comme elle l'entend. Lors de la gestion manuelle d'attachements supplémentaires de couleur ou de profondeur pour la cible de rendu, leur taille et leur nombre d'échantillons doivent toujours suivre la taille et le nombre d'échantillons de colorTexture() (ou msaaColorBuffer()), sinon des erreurs de rendu ou de validation de l'API 3D risquent de se produire.

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

cb est l'adresse QRhiCommandBuffer pour le cadre actuel. La fonction est appelée lorsqu'une image est en cours d'enregistrement, mais sans passe de rendu active. Le tampon de commande est fourni principalement pour permettre la mise en file d'attente de resource updates sans reporter à render().

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

Voir aussi render().

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

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

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

Lorsque sampleCount est plus grand que 1, et que l'antialiasage multi-échantillon est activé, le tampon retourné QRhiRenderBuffer a 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 doit également correspondre. Le contenu du multi-échantillon est censé être résolu dans la texture renvoyée par resolveTexture(). Lorsque isAutoRenderTargetEnabled est true, renderTarget() est configuré automatiquement pour faire cela, en configurant msaaColorBuffer() comme renderbuffer de l'attachement de couleur 0 et resolveTexture() comme son resolveTexture.

Lorsque MSAA n'est pas utilisé, la valeur de retour est nullptr. Utilisez alors colorTexture() à la place.

En fonction de l'API graphique 3D sous-jacente, il peut n'y avoir aucune différence pratique entre les textures multi-échantillonnées et les tampons de rendu de couleur avec un nombre d'échantillons supérieur à 1 (QRhi peut simplement mapper les deux vers le même type de ressource native). Certaines API plus anciennes peuvent cependant faire la différence 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 un multi-échantillon QRhiRenderBuffer comme attachement de couleur (et jamais un multi-échantillon QRhiTexture).

Voir aussi colorTexture(), depthStencilBuffer(), renderTarget() et resolveTexture().

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

Appelée lorsque le contenu du tampon de couleur de soutien 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 appelez depuis QML ou depuis du code C++ sur le thread principal/GUI (par exemple, lorsque vous êtes dans une fonction de définition de propriété), ou update() lorsque vous appelez depuis une fonction de rappel QQuickRhiItemRenderer. L'appel de QQuickRhiItemRenderer's update() à partir de render() entraînera un déclenchement continu des mises à jour.

cb est l'adresse QRhiCommandBuffer pour le cadre actuel. La fonction est appelée lorsqu'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 y en a un.

Voir également initialize() et synchronize().

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

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

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

Disponible uniquement si 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 et un QRhiTextureRenderTarget.

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

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

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

Renvoie la texture sans multi-échantillon dans laquelle le contenu multi-échantillon est résolu.

Le résultat est nullptr lorsque l'anticrénelage multi-échantillon 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 de graphe de scène sous-jacent de l'élément lors de la texturation d'un quad dans la passe de rendu principale de Qt Quick. Cependant, le rendu de QQuickRhiItemRenderer doit cibler le QRhiRenderBuffer (multi-échantillon) renvoyé par msaaColorBuffer(). Lorsque isAutoRenderTargetEnabled est true, cela est pris en charge par le QRhiRenderTarget renvoyé par renderTarget(). Sinon, c'est au code de la sous-classe de configurer correctement un objet de cible de rendu avec le tampon de couleur et les textures de résolution.

Voir aussi colorTexture().

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

Renvoie l'objet actuel QRhi.

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 y en a un, alors que le thread principal de l'interface graphique est bloqué. Elle est appelée à partir de the item's synchronize stepet permet de lire et d'écrire des données appartenant aux threads principal et de rendu. Généralement, les valeurs des propriétés stockées dans QQuickRhiItem sont copiées dans QQuickRhiItemRenderer, de sorte qu'elles puissent être lues en toute sécurité par la suite dans render() lorsque les threads de rendu et principal continuent à travailler en parallèle.

Voir également initialize() et render().

[protected] void QQuickRhiItemRenderer::update()

Appeler cette fonction lorsque le contenu du tampon de couleurs hors écran doit être mis à jour. (c'est-à-dire pour demander que render() soit appelé à nouveau ; l'appel aura lieu plus tard, et notez que les mises à jour sont généralement limitées au taux de présentation).

Cette fonction peut être appelée à partir de render() pour programmer une mise à jour.