QQuickWindow Class

Documentation des fonctions membres

[explicit] QQuickWindow::QQuickWindow(QQuickRenderControl *control)

Construit une fenêtre pour afficher une scène QML, dont le rendu sera contrôlé par l'objet control. Veuillez consulter la documentation de QQuickRenderControl pour plus d'informations.

[explicit] QQuickWindow::QQuickWindow(QWindow *parent = nullptr)

Construit une fenêtre pour afficher une scène QML avec la fenêtre parentale parent.

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

Détruit la fenêtre.

[override virtual] QAccessibleInterface *QQuickWindow::accessibleRoot() const

Renvoie une interface d'accessibilité pour cette fenêtre, ou 0 si une telle interface ne peut être créée.

[signal] void QQuickWindow::afterAnimating()

Ce signal est émis par le thread de l'interface graphique avant de demander au thread de rendu d'effectuer la synchronisation du graphe de scène.

Contrairement aux autres signaux similaires, celui-ci est émis dans le fil d'exécution de l'interface graphique et non dans le fil d'exécution du rendu. Il peut être utilisé pour synchroniser des systèmes d'animation externes avec le contenu QML. En même temps, cela signifie que ce signal n'est pas adapté au déclenchement d'opérations graphiques.

[signal, since 6.0] void QQuickWindow::afterFrameEnd()

Ce signal est émis lorsque le graphe de scène a soumis une image. Il est émis après tous les autres signaux connexes, tels que afterRendering(). C'est le dernier signal émis par le thread de rendu du graphe de scène lors du rendu d'une image.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi beforeFrameBegin() et rendererInterface().

[signal] void QQuickWindow::afterRenderPassRecording()

Ce signal est émis après que le graphe de scène a enregistré les commandes pour sa passe de rendu principale, mais la passe n'est pas encore finalisée sur le tampon de commande.

Ce signal est émis avant afterRendering(), et il garantit que non seulement l'image mais aussi l'enregistrement de la passe de rendu principale de la scène sont toujours actifs. Cela permet d'insérer des commandes sans avoir à générer une passe de rendu séparée (qui effacerait généralement les images jointes). Les objets graphiques natifs peuvent être interrogés via QSGRendererInterface.

Voir également rendererInterface() et Scene Graph - RHI Under QML.

[signal] void QQuickWindow::afterRendering()

Le signal est émis après que la scène graphique a ajouté ses commandes au tampon de commandes, qui n'est pas encore soumis à la file d'attente graphique. Si vous le souhaitez, la fonction slot connectée à ce signal peut interroger les ressources natives, comme le tampon de commande, avant via QSGRendererInterface. Notez cependant que la ou les passes de rendu sont déjà enregistrées à ce stade et qu'il n'est pas possible d'ajouter d'autres commandes dans la passe du graphe de scène. Utilisez plutôt afterRenderPassRecording() pour cela. Ce signal a donc une utilisation limitée dans Qt 6, contrairement à Qt 5. C'est plutôt la combinaison de beforeRendering() et beforeRenderPassRecording(), ou beforeRendering() et afterRenderPassRecording(), qui est typiquement utilisée pour obtenir une sous-couche ou une surcouche du rendu personnalisé.

Voir aussi rendererInterface(), Graphique de scène - RHI sous QML, Graphique de scène - OpenGL sous QML, Graphique de scène - Metal sous QML, Graphique de scène - Vulkan sous QML, et Graphique de scène - Direct3D 11 sous QML.

[signal] void QQuickWindow::afterSynchronizing()

Ce signal est émis après la synchronisation du graphe de scène avec l'état QML.

Ce signal peut être utilisé pour effectuer la préparation requise après les appels à QQuickItem::updatePaintNode(), alors que le thread de l'interface graphique est toujours verrouillé.

Lors de l'utilisation d'OpenGL, le QOpenGLContext utilisé pour le rendu par le graphe de scène sera lié à ce moment.

[signal, since 6.0] void QQuickWindow::beforeFrameBegin()

Ce signal est émis avant que le graphe de scène ne commence à préparer la trame. Il précède les signaux tels que beforeSynchronizing() ou beforeRendering(). C'est le premier signal émis par le thread de rendu du graphe de scène lorsqu'il commence à préparer une nouvelle image.

Ce signal est utile pour les structures graphiques de niveau inférieur qui doivent exécuter certaines opérations, telles que le nettoyage des ressources, à un stade où Qt Quick n'a pas lancé l'enregistrement d'une nouvelle image via les API de l'interface matérielle de rendu sous-jacente.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi afterFrameEnd() et rendererInterface().

[signal] void QQuickWindow::beforeRenderPassRecording()

Ce signal est émis avant que la scène ne commence à enregistrer les commandes pour la passe de rendu principale. (Les couches ont leurs propres passes et sont entièrement enregistrées au moment où ce signal est émis). La passe de rendu est déjà active sur le tampon de commande lorsque le signal est émis.

Ce signal est émis après beforeRendering() et garantit que non seulement l'image, mais aussi l'enregistrement de la passe de rendu principale de la scène sont actifs. Cela permet d'insérer des commandes sans avoir à générer une passe de rendu séparée (qui effacerait généralement les images jointes). Les objets graphiques natifs peuvent être interrogés via QSGRendererInterface.

Voir également rendererInterface() et Scene Graph - RHI Under QML.

[signal] void QQuickWindow::beforeRendering()

Ce signal est émis après que les préparatifs de la trame ont été effectués, ce qui signifie qu'il y a un tampon de commande en mode enregistrement, le cas échéant. Si vous le souhaitez, la fonction slot connectée à ce signal peut interroger les ressources natives comme la commande précédente via QSGRendererInterface. Notez cependant que l'enregistrement de la passe de rendu principale n'a pas encore commencé à ce stade et qu'il n'est pas possible d'ajouter des commandes dans cette passe. Démarrer une passe signifie vider les tampons de couleur, de profondeur et de pochoir, il n'est donc pas possible d'obtenir un rendu de type sous-couche en se connectant simplement à ce signal. Il faut plutôt se connecter à beforeRenderPassRecording(). Cependant, la connexion à ce signal reste importante si l'enregistrement de commandes de type copie est souhaité, car celles-ci ne peuvent pas être mises en file d'attente lors d'une passe de rendu.

Voir aussi rendererInterface(), Graphique de scène - RHI sous QML, Graphique de scène - OpenGL sous QML, Graphique de scène - Metal sous QML, Graphique de scène - Vulkan sous QML, et Graphique de scène - Direct3D 11 sous QML.

[signal] void QQuickWindow::beforeSynchronizing()

Ce signal est émis avant que le graphe de scène ne soit synchronisé avec l'état QML.

Même si le signal est émis par le thread de rendu du graphe de scène, le thread de l'interface graphique est garanti d'être bloqué, comme il l'est dans QQuickItem::updatePaintNode(). Par conséquent, il n'y a aucun risque à accéder aux données du fil d'exécution de l'interface graphique dans un slot ou un lambda connecté à Qt::DirectConnection.

Ce signal peut être utilisé pour effectuer toute préparation nécessaire avant les appels à QQuickItem::updatePaintNode().

Lors de l'utilisation d'OpenGL, le QOpenGLContext utilisé pour le rendu par le graphe de scène sera lié à ce point.

void QQuickWindow::beginExternalCommands()

Lorsque l'on mélange des commandes graphiques brutes (OpenGL, Vulkan, Metal, etc.) avec le rendu du graphe de scène, il est nécessaire d'appeler cette fonction avant d'enregistrer les commandes dans le tampon de commande utilisé par le graphe de scène pour effectuer sa passe de rendu principale. Cela permet d'éviter d'encombrer l'état.

En pratique, cette fonction est souvent appelée à partir d'un slot connecté aux signaux beforeRenderPassRecording() ou afterRenderPassRecording().

Il n'est pas nécessaire d'appeler cette fonction lors de l'enregistrement de commandes dans le propre tampon de commandes de l'application (par exemple, un VkCommandBuffer ou un MTLCommandBuffer + MTLRenderCommandEncoder créé et géré par l'application, et non récupéré à partir du graphe de scène). Avec les API graphiques où aucun concept de tampon de commande natif n'est exposé (OpenGL, Direct 3D 11), beginExternalCommands() et endExternalCommands() fournissent ensemble un remplacement pour la fonction Qt 3D resetOpenGLState().

L'appel à cette fonction et à endExternalCommands() n'est pas nécessaire dans l'implémentation render() d'une QSGRenderNode car le graphe de scène effectue les étapes nécessaires de manière implicite pour les nœuds de rendu.

Les objets graphiques natifs (tels que le périphérique graphique, le tampon de commande ou l'encodeur) sont accessibles via QSGRendererInterface::getResource().

Voir aussi endExternalCommands() et QQuickOpenGLUtils::resetOpenGLState().

[override virtual protected] void QQuickWindow::closeEvent(QCloseEvent *e)

Réimplémente : QWindow::closeEvent(QCloseEvent *ev).

QSGImageNode *QQuickWindow::createImageNode() const

Crée un nœud image simple. Si le graphe de scène n'est pas initialisé, la valeur de retour est null.

Il s'agit d'une alternative cross-backend à la construction directe de QSGSimpleTextureNode.

Voir aussi QSGImageNode.

QSGNinePatchNode *QQuickWindow::createNinePatchNode() const

Crée un nœud de neuf patchs. Si le graphe de scène n'est pas initialisé, la valeur de retour est null.

QSGRectangleNode *QQuickWindow::createRectangleNode() const

Crée un noeud rectangle simple. Si le graphe de scène n'est pas initialisé, la valeur de retour est null.

Il s'agit d'une alternative cross-backend à la construction directe d'un QSGSimpleRectNode.

Voir aussi QSGRectangleNode.

[since 6.7] QSGTextNode *QQuickWindow::createTextNode() const

Crée un noeud de texte. Si le graphe de scène n'est pas initialisé, la valeur de retour est null.

Cette fonction a été introduite dans Qt 6.7.

Voir aussi QSGTextNode.

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image, QQuickWindow::CreateTextureOptions options) const

Crée un nouveau QSGTexture à partir de l'image image fournie. Si l'image a un canal alpha, la texture correspondante aura un canal alpha.

L'appelant de la fonction est responsable de la suppression de la texture renvoyée. L'objet texture natif sous-jacent est alors détruit en même temps que l'objet QSGTexture.

Lorsque options contient TextureCanUseAtlas, le moteur peut placer l'image dans un atlas de textures. Les textures dans un atlas doivent s'appuyer sur QSGTexture::normalizedTextureSubRect() pour leur géométrie et ne prendront pas en charge QSGTexture::Repeat. Les autres valeurs de CreateTextureOption sont ignorées.

Lorsque options contient TextureIsOpaque, le moteur crée une texture RVB qui renvoie la valeur false pour QSGTexture::hasAlphaChannel(). Les textures opaques seront dans la plupart des cas plus rapides à rendre. Si ce drapeau n'est pas défini, la texture aura un canal alpha basé sur le format de l'image.

Lorsque options contient TextureHasMipmaps, le moteur crée une texture qui peut utiliser le filtrage mipmap. Les textures mipmap ne peuvent pas faire partie d'un atlas.

Définir TextureHasAlphaChannel dans options ne sert à rien pour cette fonction puisque l'hypothèse d'un canal alpha et d'un mélange est la valeur par défaut. Pour ne pas utiliser cette fonction, définissez TextureIsOpaque.

Lorsque le graphe de scène utilise OpenGL, la texture renvoyée utilisera GL_TEXTURE_2D comme cible de texture et GL_RGBA comme format interne. Avec d'autres API graphiques, le format de texture est généralement RGBA8. Réimplémentez QSGTexture pour créer des textures avec des paramètres différents.

Cette fonction peut être appelée à la fois par le thread principal et par le thread de rendu.

Voir également sceneGraphInitialized() et QSGTexture.

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image) const

[since 6.6] QSGTexture *QQuickWindow::createTextureFromRhiTexture(QRhiTexture *texture, QQuickWindow::CreateTextureOptions options = {}) const

Crée un nouveau QSGTexture à partir du texture fourni.

Utilisez options pour personnaliser les attributs de la texture. Seul le drapeau TextureHasAlphaChannel est pris en compte par cette fonction. Lorsqu'il est activé, le moteur de rendu du graphe de scène considère toujours que l'image QSGTexture doit être mélangée. Pour les textures totalement opaques, le fait de ne pas activer l'indicateur permet d'économiser le coût de l'alpha-blanchiment pendant le rendu. L'indicateur n'a pas de correspondance directe avec le format du QRhiTexture, c'est-à-dire qu'il est tout à fait normal de ne pas activer l'indicateur tout en ayant un format de texture tel que le QRhiTexture::RGBA8 couramment utilisé.

La cartographie n'est pas contrôlée par options puisque texture est déjà créé et que la présence ou l'absence de cartographie y est intégrée.

Le site QSGTexture retourné possède le site QRhiTexture, ce qui signifie que le site texture est détruit en même temps que le site QSGTexture retourné.

Si texture possède ses ressources graphiques natives sous-jacentes (objet de texture OpenGL, image Vulkan, etc.), cela dépend de la façon dont QRhiTexture a été créé (QRhiTexture::create() ou QRhiTexture::createFrom()), et cela n'est pas contrôlé ou modifié par cette fonction.

Cette fonction a été introduite dans Qt 6.6.

Voir aussi createTextureFromImage(), sceneGraphInitialized(), et QSGTexture.

[signal, since 6.11] void QQuickWindow::devicePixelRatioChanged()

Ce signal est émis lorsque le rapport de pixels effectif de l'appareil a été modifié.

Cette fonction a été introduite dans Qt 6.11.

Voir aussi effectiveDevicePixelRatio().

qreal QQuickWindow::effectiveDevicePixelRatio() const

Renvoie le ratio de pixels de l'appareil pour cette fenêtre.

Cette fonction est différente de QWindow::devicePixelRatio() dans la mesure où elle prend en charge le rendu redirigé via QQuickRenderControl et QQuickRenderTarget. Lors de l'utilisation de QQuickRenderControl, la fenêtre QQuickWindow n'est souvent pas entièrement créée, ce qui signifie qu'elle n'est jamais affichée et qu'il n'y a pas de fenêtre native sous-jacente créée dans le système de fenêtrage. Par conséquent, l'interrogation de propriétés telles que le rapport de pixels de l'appareil ne peut pas donner de résultats corrects. Cette fonction prend en compte à la fois QQuickRenderControl::renderWindowFor() et QQuickRenderTarget::devicePixelRatio(). Lorsqu'il n'y a pas de redirection, le résultat est le même que celui de QWindow::devicePixelRatio().

Voir aussi QQuickRenderControl, QQuickRenderTarget, setRenderTarget(), et QWindow::devicePixelRatio().

void QQuickWindow::endExternalCommands()

Lorsque l'on mélange des commandes graphiques brutes (OpenGL, Vulkan, Metal, etc.) avec le rendu du graphe de scène, il est nécessaire d'appeler cette fonction après avoir enregistré les commandes dans le tampon de commande utilisé par le graphe de scène pour effectuer sa passe de rendu principale. Ceci afin d'éviter d'endommager l'état.

En pratique, cette fonction est souvent appelée à partir d'un slot connecté aux signaux beforeRenderPassRecording() ou afterRenderPassRecording().

Il n'est pas nécessaire d'appeler cette fonction lors de l'enregistrement de commandes dans le propre tampon de commandes de l'application (par exemple, un VkCommandBuffer ou un MTLCommandBuffer + MTLRenderCommandEncoder créé et géré par l'application, et non récupéré à partir du graphe de scène). Avec les API graphiques où aucun concept de tampon de commande natif n'est exposé (OpenGL, Direct 3D 11), beginExternalCommands() et endExternalCommands() fournissent ensemble un remplacement pour la fonction Qt 3D resetOpenGLState().

L'appel à cette fonction et à beginExternalCommands() n'est pas nécessaire dans l'implémentation render() d'une QSGRenderNode car le graphe de scène effectue implicitement les étapes nécessaires pour les nœuds de rendu.

Voir également beginExternalCommands() et QQuickOpenGLUtils::resetOpenGLState().

[override virtual protected] bool QQuickWindow::event(QEvent *event)

Réimplémente : QWindow::event(QEvent *ev).

[override virtual protected] void QQuickWindow::exposeEvent(QExposeEvent *)

Réimplémente : QWindow::exposeEvent(QExposeEvent *ev).

[override virtual protected] void QQuickWindow::focusInEvent(QFocusEvent *ev)

Réimplémente : QWindow::focusInEvent(QFocusEvent *ev).

[override virtual protected] void QQuickWindow::focusOutEvent(QFocusEvent *ev)

Réimplémente : QWindow::focusOutEvent(QFocusEvent *ev).

[signal] void QQuickWindow::frameSwapped()

Ce signal est émis lorsqu'une image a été mise en file d'attente pour être présentée. Lorsque la synchronisation verticale est activée, le signal est émis au maximum une fois par intervalle vsync dans une scène animée en continu.

Ce signal est émis par le thread de rendu du graphe de scène.

QImage QQuickWindow::grabWindow()

Saisit le contenu de la fenêtre et le renvoie sous forme d'image.

Il est possible d'appeler la fonction grabWindow() lorsque la fenêtre n'est pas visible. Pour cela, il faut que la fenêtre soit created, qu'elle ait une taille valide et qu'aucune autre instance QQuickWindow ne soit en cours de rendu dans le même processus.

[static, since 6.0] QSGRendererInterface::GraphicsApi QQuickWindow::graphicsApi()

Renvoie l'API graphique qui serait utilisée par le graphe de scène s'il était initialisé à ce moment précis.

La manière standard d'interroger l'API utilisée par le graphe de scène est d'utiliser QSGRendererInterface::graphicsApi() une fois que le graphe de scène a été initialisé, par exemple lorsque ou après que le signal sceneGraphInitialized() a été émis. Dans ce cas, on obtient le vrai résultat, car on sait alors que tout a été initialisé correctement à l'aide de cette API graphique.

Cela n'est pas toujours pratique. Si l'application doit mettre en place des cadres externes ou travailler avec setGraphicsDevice() d'une manière qui dépend de la logique de sélection de l'API intégrée dans le graphe de scène, il n'est pas toujours possible de différer ces opérations jusqu'à ce que QQuickWindow ait été rendu visible ou que QQuickRenderControl::initialize() ait été appelé.

C'est pourquoi cette fonction statique est fournie en contrepartie de setGraphicsApi() : elle peut être appelée à tout moment et le résultat reflète l'API que le graphe de scène choisirait s'il était initialisé au moment de l'appel.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi setGraphicsApi().

[since 6.0] QQuickGraphicsConfiguration QQuickWindow::graphicsConfiguration() const

Retourne le QQuickGraphicsConfiguration passé à setGraphicsConfiguration(), ou un construit par défaut dans le cas contraire.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi setGraphicsConfiguration().

[since 6.0] QQuickGraphicsDevice QQuickWindow::graphicsDevice() const

Retourne le QQuickGraphicsDevice passé à setGraphicsDevice(), ou un construit par défaut dans le cas contraire

Cette fonction a été introduite dans Qt 6.0.

Voir aussi setGraphicsDevice().

const QQuickWindow::GraphicsStateInfo &QQuickWindow::graphicsStateInfo()

Renvoie une référence à une structure GraphicsStateInfo décrivant l'état interne du RHI, en particulier l'état de la double ou triple mise en mémoire tampon du backend (comme les intégrations Vulkan ou Metal). Ceci est pertinent lorsque les API graphiques sous-jacentes sont Vulkan ou Metal, et que le code de rendu externe souhaite effectuer une double ou triple mise en mémoire tampon de ses propres ressources qui changent souvent, telles que les tampons uniformes, afin d'éviter de bloquer le pipeline.

[static] bool QQuickWindow::hasDefaultAlphaBuffer()

Indique s'il faut utiliser la transparence alpha pour les fenêtres nouvellement créées.

Voir également setDefaultAlphaBuffer().

[override virtual protected] void QQuickWindow::hideEvent(QHideEvent *)

Réimplémente : QWindow::hideEvent(QHideEvent *ev).

QQmlIncubationController *QQuickWindow::incubationController() const

Renvoie un contrôleur d'incubation qui joint l'incubation entre les cadres pour cette fenêtre. QQuickView installe automatiquement ce contrôleur pour vous, sinon vous devrez l'installer vous-même à l'aide de QQmlEngine::setIncubationController().

Le contrôleur appartient à la fenêtre et sera détruit lorsque la fenêtre sera supprimée.

bool QQuickWindow::isPersistentGraphics() const

Retourne si les ressources graphiques essentielles peuvent être libérées pendant la durée de vie du site QQuickWindow.

Voir également setPersistentGraphics().

bool QQuickWindow::isPersistentSceneGraph() const

Indique si les nœuds et les ressources du graphe de scène peuvent être libérés pendant la durée de vie de cette page QQuickWindow.

bool QQuickWindow::isSceneGraphInitialized() const

Retourne true si le graphe de scène a été initialisé, sinon retourne false.

[override virtual protected] void QQuickWindow::keyPressEvent(QKeyEvent *e)

Réimplémente : QWindow::keyPressEvent(QKeyEvent *ev).

[override virtual protected] void QQuickWindow::keyReleaseEvent(QKeyEvent *e)

Réimplémente : QWindow::keyReleaseEvent(QKeyEvent *ev).

[override virtual protected] void QQuickWindow::mouseDoubleClickEvent(QMouseEvent *event)

Réimplémente : QWindow::mouseDoubleClickEvent(QMouseEvent *ev).

[override virtual protected] void QQuickWindow::mouseMoveEvent(QMouseEvent *event)

Réimplémente : QWindow::mouseMoveEvent(QMouseEvent *ev).

[override virtual protected] void QQuickWindow::mousePressEvent(QMouseEvent *event)

Réimplémente : QWindow::mousePressEvent(QMouseEvent *ev).

[override virtual protected] void QQuickWindow::mouseReleaseEvent(QMouseEvent *event)

Réimplémente : QWindow::mouseReleaseEvent(QMouseEvent *ev).

[slot] void QQuickWindow::releaseResources()

Cette fonction tente de libérer les ressources redondantes actuellement détenues par la scène QML.

L'appel de cette fonction demande au graphe de scène de libérer les ressources graphiques mises en cache, telles que les objets du pipeline graphique, les programmes de shaders ou les données d'image.

En outre, en fonction de la boucle de rendu utilisée, cette fonction peut également entraîner la libération du graphe de scène et de toutes les ressources de rendu liées à la fenêtre. Dans ce cas, le signal sceneGraphInvalidated() est émis, ce qui permet aux utilisateurs de nettoyer leurs propres ressources graphiques. Les fonctions setPersistentGraphics() et setPersistentSceneGraph() peuvent être utilisées pour éviter cela, si la gestion du nettoyage n'est pas possible dans l'application, au prix d'une utilisation plus importante de la mémoire.

Voir également sceneGraphInvalidated(), setPersistentGraphics() et setPersistentSceneGraph().

[since 6.0] QQuickRenderTarget QQuickWindow::renderTarget() const

Retourne le QQuickRenderTarget passé à setRenderTarget(), ou un construit par défaut dans le cas contraire

Cette fonction a été introduite dans Qt 6.0.

Voir aussi setRenderTarget().

QSGRendererInterface *QQuickWindow::rendererInterface() const

Renvoie l'interface de rendu actuelle. La valeur est toujours valide et n'est jamais nulle.

Voir également QSGRenderNode et QSGRendererInterface.

[override virtual protected] void QQuickWindow::resizeEvent(QResizeEvent *ev)

Réimplémente : QWindow::resizeEvent(QResizeEvent *ev).

[since 6.6] QRhi *QQuickWindow::rhi() const

Renvoie l'objet QRhi utilisé par cette fenêtre pour le rendu.

Disponible uniquement lorsque la fenêtre utilise les abstractions de l'API 3D et du langage d'ombrage de Qt, ce qui signifie que le résultat est toujours nul lors de l'utilisation de l'adaptation software.

Le résultat n'est valide que lorsque le rendu a été initialisé, ce qui est indiqué par l'émission du signal sceneGraphInitialized(). Avant cela, la valeur renvoyée est nulle. Dans le cas d'un jeu de scène QQuickWindow ordinaire, l'initialisation se produit généralement lorsque la fenêtre native est exposée (affichée) pour la première fois. Lorsque l'on utilise QQuickRenderControl, l'initialisation est effectuée dans l'appel explicite initialize().

En pratique, cette fonction est un raccourci pour interroger QRhi via QSGRendererInterface.

Cette fonction a été introduite dans Qt 6.6.

[signal] void QQuickWindow::sceneGraphAboutToStop()

Ce signal est émis sur le thread de rendu lorsque le graphe de scène est sur le point d'arrêter le rendu. Cela se produit généralement parce que la fenêtre a été cachée.

Les applications peuvent utiliser ce signal pour libérer des ressources, mais doivent être prêtes à les réintégrer rapidement. Le graphe de scène et le contexte graphique ne sont pas libérés à ce moment-là.

Voir aussi sceneGraphInvalidated().

[static] QString QQuickWindow::sceneGraphBackend()

Renvoie le backend Qt Quick scenegraph demandé.

Voir aussi setSceneGraphBackend().

[signal] void QQuickWindow::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)

Ce signal est émis lorsqu'une erreur error s'est produite lors de l'initialisation du graphe de scène.

Les applications doivent se connecter à ce signal si elles souhaitent gérer les erreurs, comme les échecs de création de contexte graphique, d'une manière personnalisée. Si aucun slot n'est connecté au signal, le comportement sera différent : Quick imprimera le message message, ou affichera une boîte de message, et mettra fin à l'application.

Ce signal sera émis par le thread de l'interface graphique.

[signal] void QQuickWindow::sceneGraphInitialized()

Ce signal est émis lorsque le graphe de scène a été initialisé.

Ce signal sera émis par le thread de rendu du graphe de scène.

[signal] void QQuickWindow::sceneGraphInvalidated()

Ce signal est émis lorsque le graphe de scène a été invalidé.

Ce signal implique que le contexte de rendu graphique utilisé a été invalidé et que toutes les ressources utilisateur liées à ce contexte doivent être libérées.

Lors d'un rendu avec OpenGL, l'adresse QOpenGLContext de cette fenêtre sera liée lorsque cette fonction sera appelée. La seule exception est si l'OpenGL natif a été détruit en dehors du contrôle de Qt, par exemple par EGL_CONTEXT_LOST.

Ce signal sera émis par le thread de rendu du graphe de scène.

void QQuickWindow::scheduleRenderJob(QRunnable *job, QQuickWindow::RenderStage stage)

Planifie l'exécution de job lorsque le rendu de cette fenêtre atteint la valeur donnée stage.

Il s'agit d'une commodité par rapport aux signaux équivalents dans QQuickWindow pour les tâches "ponctuelles".

La fenêtre est propriétaire de job et l'efface lorsque la tâche est terminée.

Si le rendu est arrêté avant que job n'ait eu le temps de s'exécuter, la tâche sera exécutée puis supprimée dans le cadre du nettoyage du graphe de la scène. Si la fenêtre n'est jamais affichée et qu'aucun rendu n'a lieu avant la destruction de QQuickWindow, tous les travaux en attente seront détruits sans que leur méthode run() ne soit appelée.

Si le rendu a lieu dans un autre thread, le job sera exécuté dans le thread de rendu.

Si stage est NoStage, job sera exécuté à la première occasion lorsque le thread de rendu n'est pas occupé à rendre une image. Si la fenêtre n'est pas exposée et ne peut pas être rendue au moment où le travail est affiché ou traité, le travail est supprimé sans que la méthode run() ne soit exécutée. Si un moteur de rendu non threadé est utilisé, la méthode run() du travail est exécutée de manière synchrone. Lors d'un rendu avec OpenGL, le contexte OpenGL est remplacé par le contexte du moteur de rendu avant l'exécution de tout travail, y compris les travaux NoStage.

Voir aussi beforeRendering(), afterRendering(), beforeSynchronizing(), afterSynchronizing(), frameSwapped() et sceneGraphInvalidated().

[static] void QQuickWindow::setDefaultAlphaBuffer(bool useAlpha)

useAlpha spécifie s'il faut utiliser la transparence alpha pour les fenêtres nouvellement créées.

Dans toute application qui s'attend à créer des fenêtres translucides, il est nécessaire de fixer cette valeur à true avant de créer la première fenêtre QQuickWindow. La valeur par défaut est false.

Voir également hasDefaultAlphaBuffer().

[static, since 6.0] void QQuickWindow::setGraphicsApi(QSGRendererInterface::GraphicsApi api)

Demande l'adaptation graphique spécifiée api.

Lorsque l'adaptation graphique intégrée par défaut est utilisée, api spécifie l'API graphique (OpenGL, Vulkan, Metal ou Direct3D) que le graphe de scène doit utiliser pour le rendu. En outre, le backend software est également intégré et peut être demandé en définissant api sur QSGRendererInterface::Software.

Contrairement à setSceneGraphBackend(), qui ne peut être utilisé que pour demander un backend donné (intégré ou installé sous forme de plugins chargés dynamiquement), cette fonction fonctionne avec le concept de plus haut niveau des API graphiques. Elle couvre les backends qui sont livrés avec Qt Quick, et qui ont donc des valeurs correspondantes dans l'énumération QSGRendererInterface::GraphicsApi.

Lorsque cette fonction n'est pas appelée et que la variable d'environnement équivalente QSG_RHI_BACKEND n'est pas définie non plus, le graphe de scène choisit l'API graphique à utiliser en fonction de la plateforme.

Cette fonction devient importante dans les applications qui ne sont préparées qu'au rendu avec une API donnée. Par exemple, si l'application effectue un rendu OpenGL ou Vulkan natif, elle voudra s'assurer que Qt Quick effectue également le rendu avec OpenGL ou Vulkan. Ces applications devraient appeler cette fonction au début de leur fonction main().

Pour demander quelle API graphique le graphe de scène utilise pour le rendu, QSGRendererInterface::graphicsApi() après le graphe de scène has initialized, ce qui se produit généralement lorsque la fenêtre devient visible pour la première fois ou lorsque QQuickRenderControl::initialize() est appelé.

Pour revenir au comportement par défaut, où le graphe de scène choisit une API graphique en fonction de la plate-forme et d'autres conditions, définissez api à QSGRendererInterface::Unknown.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi graphicsApi().

[since 6.0] void QQuickWindow::setGraphicsConfiguration(const QQuickGraphicsConfiguration &config)

Définit la configuration graphique pour cette fenêtre. config contient divers paramètres qui peuvent être pris en compte par le graphe de scène lors de l'initialisation des périphériques et contextes graphiques sous-jacents.

Une telle configuration supplémentaire, spécifiant par exemple quelles extensions de périphériques activer pour Vulkan, devient pertinente et essentielle lors de l'intégration d'un code de rendu graphique natif qui s'appuie sur certaines extensions. Il en va de même lors de l'intégration avec un moteur 3D ou VR externe, tel qu'OpenXR.

QQuickGraphicsConfiguration Les instances sont implicitement partagées, copiables et peuvent être transmises par valeur.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi graphicsConfiguration().

[since 6.0] void QQuickWindow::setGraphicsDevice(const QQuickGraphicsDevice &device)

Définit les objets de périphérique graphique pour cette fenêtre. Au lieu de créer de nouveaux objets, le scenegraph utilisera les objets existants (device, physical device, etc.) spécifiés par device.

Cette fonction est très souvent utilisée en combinaison avec QQuickRenderControl et setRenderTarget(), afin de rediriger le rendu de Qt Quick dans une texture.

Un QQuickGraphicsDevice construit par défaut ne modifie en rien le comportement par défaut. Une fois qu'un device créé via l'une des fonctions d'usine QQuickGraphicsDevice, telles que QQuickGraphicsDevice::fromDeviceObjects(), est passé, et que le scenegraph utilise une API graphique correspondante (avec l'exemple de fromDeviceObjects(), ce serait Vulkan), le scenegraph utilisera les objets de périphérique existants (tels que VkPhysicalDevice, VkDevice, et l'index de la famille de la file d'attente graphique, dans le cas de Vulkan) encapsulés par QQuickGraphicsDevice. Cela permet d'utiliser le même périphérique et de partager les ressources, telles que les tampons et les textures, entre Qt Quick et les moteurs de rendu natifs.

À titre d'exemple, cette fois avec Direct3D, l'utilisation typique devrait être la suivante :

// native graphics resources set up by a custom D3D rendering engine
ID3D11Device *device;
ID3D11DeviceContext *context;
ID3D11Texture2D *texture;
...
// now to redirect Qt Quick content into 'texture' we could do the following:
QQuickRenderControl *renderControl = new QQuickRenderControl;
QQuickWindow *window = new QQuickWindow(renderControl); // this window will never be shown on-screen
...
window->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(device, context));
renderControl->initialize();
window->setRenderTarget(QQuickRenderTarget::fromD3D11Texture(texture, textureSize);
...

L'aspect essentiel de l'utilisation de cette fonction est de s'assurer que les ressources ou les handles vers les ressources, tels que texture dans l'exemple ci-dessus, sont visibles et utilisables à la fois par le moteur de rendu externe et par le moteur de rendu de la scène. Il faut pour cela utiliser le même périphérique graphique (ou, avec OpenGL, le contexte OpenGL).

QQuickGraphicsDevice Les instances sont implicitement partagées, copiables et peuvent être transmises par valeur. Elles ne possèdent pas les objets natifs associés (comme l'ID3D11Device dans l'exemple).

Cette fonction a été introduite dans Qt 6.0.

Voir aussi graphicsDevice(), QQuickRenderControl, setRenderTarget(), et setGraphicsApi().

void QQuickWindow::setPersistentGraphics(bool persistent)

Définit si les ressources graphiques (périphérique graphique ou contexte, chaîne de permutation, tampons, textures) doivent être préservées et ne peuvent pas être libérées avant la suppression de la dernière fenêtre, à persistent. La valeur par défaut est true.

Lors de l'appel à releaseResources(), ou lorsque la fenêtre est cachée (plus précisément, ne peut être rendue), certaines boucles de rendu ont la possibilité de libérer toutes les ressources graphiques, et pas seulement celles qui sont mises en cache. Cela peut libérer temporairement de la mémoire, mais cela signifie aussi que le moteur de rendu devra réinitialiser complètement les ressources, ce qui peut être coûteux, lorsque la fenêtre devra être rendue à nouveau.

Voir aussi isPersistentGraphics(), setPersistentSceneGraph(), sceneGraphInitialized(), sceneGraphInvalidated(), et releaseResources().

void QQuickWindow::setPersistentSceneGraph(bool persistent)

Définit si les nœuds et les ressources du graphe de scène sont persistent. Persistant signifie que les nœuds et les ressources ne peuvent pas être libérés. La valeur par défaut est true.

Lors de l'appel à releaseResources(), lorsque la fenêtre est cachée (plus précisément, qu'elle ne peut pas être rendue), certaines boucles de rendu ont la possibilité de libérer les nœuds du graphe de scène et les ressources graphiques correspondantes. Cela libère temporairement de la mémoire, mais signifie également que le graphe de scène devra être reconstruit lors du prochain rendu de la fenêtre.

Voir également isPersistentSceneGraph(), setPersistentGraphics(), sceneGraphInvalidated(), sceneGraphInitialized() et releaseResources().

[since 6.0] void QQuickWindow::setRenderTarget(const QQuickRenderTarget &target)

Définit la cible de rendu de cette fenêtre comme étant target.

Une adresse QQuickRenderTarget sert de poignée opaque pour un objet natif pouvant être rendu, le plus souvent une texture 2D, et les métadonnées associées, telles que la taille en pixels.

Un QQuickRenderTarget construit par défaut signifie qu'il n'y a pas de redirection. En revanche, un target valide, créé via l'une des fonctions d'usine statiques QQuickRenderTarget, permet de rediriger le rendu de la scène Qt Quick: il ne ciblera plus les tampons de couleur pour la surface associée à la fenêtre, mais plutôt les textures ou d'autres objets graphiques spécifiés dans target.

Par exemple, en supposant que la scène utilise Vulkan pour effectuer le rendu, on peut rediriger sa sortie dans un VkImage. Pour les API graphiques comme Vulkan, la disposition de l'image doit également être fournie. Les instances QQuickRenderTarget sont implicitement partagées, copiables et peuvent être transmises par valeur. Elles ne possèdent cependant pas les objets natifs associés (comme le VkImage dans l'exemple).

QQuickRenderTarget rt = QQuickRenderTarget::fromVulkanImage(vulkanImage, VK_IMAGE_LAYOUT_PREINITIALIZED, pixelSize);
quickWindow->setRenderTarget(rt);

Cette fonction est très souvent utilisée en combinaison avec QQuickRenderControl et une QQuickWindow invisible, afin de rendre le contenu de Qt Quick dans une texture, sans créer de fenêtre native à l'écran pour cette QQuickWindow.

Lorsque la cible souhaitée ou les données associées, telles que la taille, changent, appelez cette fonction avec un nouveau QQuickRenderTarget. La construction d'instances QQuickRenderTarget et l'appel de cette fonction sont peu coûteux, mais il faut savoir que la définition d'un nouveau target avec un objet natif différent ou d'autres données peut entraîner des étapes d'initialisation potentiellement coûteuses lorsque la scène est sur le point de rendre l'image suivante. Par conséquent, ne modifiez la cible qu'en cas de nécessité.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi renderTarget(), QQuickRenderControl, setGraphicsDevice(), et setGraphicsApi().

[static] void QQuickWindow::setSceneGraphBackend(const QString &backend)

Demande une scène Qt Quick backend . Les backends peuvent être intégrés ou installés sous la forme de plugins chargés dynamiquement.

Pour plus d'informations sur la liste des backends, voir Passer d'une adaptation à l'autre dans votre application. Si backend n'est pas valide ou si une erreur se produit, la demande est ignorée.

Voir aussi sceneGraphBackend().

[static] void QQuickWindow::setTextRenderType(QQuickWindow::TextRenderType renderType)

Définit le type de rendu par défaut des éléments de type texte dans Qt Quick à renderType.

Voir aussi textRenderType().

[override virtual protected] void QQuickWindow::showEvent(QShowEvent *)

Réimplémente : QWindow::showEvent(QShowEvent *ev).

[since 6.6] QRhiSwapChain *QQuickWindow::swapChain() const

Retourne le site QRhiSwapChain utilisé par cette fenêtre, s'il y en a un.

Cette fonction a été introduite dans Qt 6.6.

[override virtual protected] void QQuickWindow::tabletEvent(QTabletEvent *event)

Réimplémente : QWindow::tabletEvent(QTabletEvent *ev).

[static] QQuickWindow::TextRenderType QQuickWindow::textRenderType()

Renvoie le type de rendu des éléments de type texte dans Qt Quick. La valeur par défaut est QQuickWindow::QtTextRendering.

Voir aussi setTextRenderType().

[slot] void QQuickWindow::update()

Planifie le rendu d'une autre image de la fenêtre.

L'appel à QQuickWindow::update() diffère de QQuickItem::update() en ce sens qu'il déclenche toujours un repeint, indépendamment des changements dans le graphe de scène sous-jacent.

[override virtual protected] void QQuickWindow::wheelEvent(QWheelEvent *event)

Réimplémente : QWindow::wheelEvent(QWheelEvent *ev).