Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QQuickRenderControl Class

La classe QQuickRenderControl fournit un mécanisme de rendu de la scène Qt Quick sur une cible de rendu hors écran d'une manière entièrement contrôlée par l'application. Plus d'informations...

En-tête : #include <QQuickRenderControl>
CMake : find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake : QT += quick
Héritages : QObject

Fonctions publiques

QQuickRenderControl(QObject *parent = nullptr)
virtual ~QQuickRenderControl() override
(since 6.0) void beginFrame()
(since 6.6) QRhiCommandBuffer *commandBuffer() const
(since 6.0) void endFrame()
(since 6.0) bool initialize()
void invalidate()
void polishItems()
void prepareThread(QThread *targetThread)
void render()
virtual QWindow *renderWindow(QPoint *offset)
(since 6.6) QRhi *rhi() const
(since 6.0) int samples() const
(since 6.0) void setSamples(int sampleCount)
bool sync()
(since 6.0) QQuickWindow *window() const

Signaux

void renderRequested()
void sceneChanged()

Membres publics statiques

QWindow *renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr)

Description détaillée

QQuickWindow et QQuickView et leurs boucles de rendu internes associées effectuent le rendu de la scène Qt Quick sur une fenêtre native. Dans certains cas, par exemple lors de l'intégration avec des moteurs de rendu OpenGL, Vulkan, Metal ou Direct 3D tiers, il peut être utile d'obtenir la scène dans une texture qui peut ensuite être utilisée de manière arbitraire par le moteur de rendu externe. Un tel mécanisme est également essentiel lors de l'intégration avec un framework VR. QQuickRenderControl rend cela possible d'une manière accélérée au niveau matériel, contrairement à l'alternative limitée en termes de performances que constitue l'utilisation de QQuickWindow::grabWindow().

Lors de l'utilisation d'un QQuickRenderControl, le site QQuickWindow ne doit pas être shown (il ne sera pas visible à l'écran) et il n'y aura pas de fenêtre native sous-jacente pour lui. Au lieu de cela, l'instance QQuickWindow est associée à l'objet de contrôle de rendu, en utilisant la surcharge du constructeur QQuickWindow, et à un objet de texture ou d'image spécifié via QQuickWindow::setRenderTarget(). L'objet QQuickWindow reste essentiel, car il représente la scène Qt Quick et fournit l'essentiel des mécanismes de gestion de la scène et de fourniture d'événements. Il n'agit cependant pas comme une véritable fenêtre à l'écran du point de vue du système de fenêtrage.

La gestion des périphériques graphiques, des contextes, des images et des objets de texture incombe à l'application. Le périphérique ou le contexte qui sera utilisé par Qt Quick doit être créé avant d'appeler initialize(). La création de l'objet texture peut être différée, voir ci-dessous. Qt 5.4 introduit la possibilité pour QOpenGLContext d'adopter des contextes natifs existants. Avec QQuickRenderControl, cela permet de créer un QOpenGLContext qui partage le contexte existant d'un moteur de rendu externe. Ce nouveau QOpenGLContext peut alors être utilisé pour rendre la scène Qt Quick dans une texture accessible également par le contexte de l'autre moteur. Pour Vulkan, Metal et Direct 3D, il n'y a pas d'enveloppe fournie par Qt pour les objets de périphérique, de sorte que les objets existants peuvent être passés tels quels via QQuickWindow::setGraphicsDevice().

Le chargement et l'instanciation des composants QML s'effectuent à l'aide d'un QQmlEngine. Une fois l'objet racine créé, il devra être parenté au contentItem() du QQuickWindow.

Les applications doivent généralement se connecter à quatre signaux importants :

Pour envoyer des événements, par exemple des événements de souris ou de clavier, à la scène, utilisez QCoreApplication::sendEvent() avec l'instance QQuickWindow comme récepteur.

Pour les événements clés, il peut également être nécessaire de placer manuellement le focus sur l'élément souhaité. En pratique, cela implique d'appeler forceActiveFocus() sur l'élément souhaité, par exemple l'élément racine de la scène, une fois qu'il est associé à la scène ( QQuickWindow).

Documentation des fonctions membres

[explicit] QQuickRenderControl::QQuickRenderControl(QObject *parent = nullptr)

Construit un objet QQuickRenderControl, avec l'objet parent parent.

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

Détruit l'instance. Libère toutes les ressources du graphe de scène.

Voir aussi invalidate().

[since 6.0] void QQuickRenderControl::beginFrame()

Spécifie le début d'une image graphique. Les appels à sync() ou render() doivent être suivis d'appels à beginFrame() et endFrame().

Contrairement à l'ancien monde OpenGL de Qt 5, le rendu avec d'autres API graphiques nécessite des points de départ et d'arrivée d'une image mieux définis. Lors du pilotage manuel de la boucle de rendu via QQuickRenderControl, il incombe maintenant à l'utilisateur de QQuickRenderControl de spécifier ces points.

Une étape de mise à jour typique, y compris l'initialisation du rendu dans une texture existante, pourrait ressembler à ce qui suit. L'exemple prend pour base Direct3D 11, mais les mêmes concepts s'appliquent également à d'autres API graphiques.

if (!m_quickInitialized) {  m_quickWindow->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(m_engine->device(),  m_engine->context())) ; if (!m_renderControl->initialize())        qWarning("Failed to initialize redirected Qt Quick rendering");

    m_quickWindow->setRenderTarget(QQuickRenderTarget::fromNativeTexture({ quint64(m_res.texture), 0},  QSize(QML_WIDTH, QML_HEIGHT),SAMPLE_COUNT)) ; m_quickInitialized = true; }  m_renderControl->polishItems() ;  m_renderControl->beginFrame() ;  m_renderControl->sync() ;  m_renderControl->render() ;  m_renderControl->endFrame() ; // Les commandes de rendu de Qt Quick sont soumises au contexte du périphérique ici

Note : Cette fonction n'a pas besoin d'être appelée, et ne doit pas l'être, lors de l'utilisation de l'adaptation software de Qt Quick.

Note : En interne, beginFrame() et endFrame() invoquent respectivement beginOffscreenFrame() et endOffscreenFrame(). Cela implique qu'il ne doit pas y avoir de trame (ni hors écran, ni basée sur la chaîne d'échange) en cours d'enregistrement sur le site QRhi lorsque cette fonction est appelée.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi endFrame(), initialize(), sync(), render(), QQuickGraphicsDevice, et QQuickRenderTarget.

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

Renvoie le tampon de commande actuel.

Une fois que beginFrame() est appelé, un QRhiCommandBuffer est automatiquement mis en place. C'est le tampon de commande utilisé par Qt Quick scenegraph, mais dans certains cas, les applications peuvent également vouloir l'interroger, par exemple pour émettre des mises à jour de ressources (par exemple, une lecture de texture).

La référence au tampon de commande renvoyée ne doit être utilisée qu'entre beginFrame() et endFrame(). Il existe des exceptions spécifiques, par exemple l'appel à lastCompletedGpuTime() sur le tampon de commande juste après endFrame(), mais avant le prochain beginFrame(), est valide.

Remarque : cette fonction n'est pas applicable et renvoie un résultat nul lorsque l'on utilise l'adaptation software de Qt Quick.

Cette fonction a été introduite dans Qt 6.6.

Voir aussi rhi(), beginFrame(), et endFrame().

[since 6.0] void QQuickRenderControl::endFrame()

Spécifie la fin d'une image graphique. Les appels à sync() ou render() doivent être suivis d'appels à beginFrame() et endFrame().

Lorsque cette fonction est appelée, toutes les commandes graphiques mises en file d'attente par le scenegraph sont soumises au contexte ou à la file d'attente des commandes, selon le cas.

Remarque : cette fonction n'a pas besoin d'être appelée, et ne doit pas l'être, lors de l'utilisation de l'adaptation software de Qt Quick.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi beginFrame(), initialize(), sync(), render(), QQuickGraphicsDevice, et QQuickRenderTarget.

[since 6.0] bool QQuickRenderControl::initialize()

Initialise les ressources du graphe de scène. Lors de l'utilisation d'une API graphique, telle que Vulkan, Metal, OpenGL ou Direct3D, pour le rendu Qt Quick, QQuickRenderControl mettra en place un moteur de rendu approprié lorsque cette fonction sera appelée. Cette infrastructure de rendu existe tant que le site QQuickRenderControl existe.

Pour contrôler l'API graphique utilisée par Qt Quick, appelez QQuickWindow::setGraphicsApi() avec l'une des constantes QSGRendererInterface:GraphicsApi. Cela doit être fait avant d'appeler cette fonction.

Pour éviter que le graphe de scène ne crée ses propres objets de périphérique et de contexte, spécifiez un QQuickGraphicsDevice approprié, en enveloppant les objets graphiques existants, en appelant QQuickWindow::setGraphicsDevice().

Pour configurer les extensions de périphériques à activer (par exemple, pour Vulkan), appelez QQuickWindow::setGraphicsConfiguration() avant cette fonction.

Remarque : lors de l'utilisation de Vulkan, QQuickRenderControl ne crée pas automatiquement un QVulkanInstance. Il incombe plutôt à l'application de créer un QVulkanInstance et un associate it appropriés avec le QQuickWindow. Avant d'initialiser le QVulkanInstance, il est fortement recommandé d'interroger la liste des extensions d'instance souhaitées du Qt Quick en appelant la fonction statique QQuickGraphicsConfiguration::preferredInstanceExtensions() et de transmettre la liste renvoyée à QVulkanInstance::setExtensions().

Retourne true en cas de succès, false dans le cas contraire.

Remarque : cette fonction n'a pas besoin d'être appelée, et ne doit pas l'être, lorsque l'on utilise l'adaptation software de Qt Quick.

Avec l'adaptation par défaut de Qt Quick, cette fonction crée un nouvel objet QRhi, de la même manière que ce qui se passerait avec un QQuickWindow à l'écran lorsque QQuickRenderControl n'est pas utilisé. Pour que ce nouvel objet QRhi adopte un dispositif existant ou une ressource contextuelle (par exemple, utiliser un objet QOpenGLContext existant au lieu d'en créer un nouveau), il convient d'utiliser QQuickWindow::setGraphicsDevice() comme indiqué ci-dessus. Lorsque l'application souhaite que le rendu Qt Quick utilise un objet QRhi déjà existant, cela est également possible via QQuickGraphicsDevice::fromRhi(). Lorsqu'un tel QQuickGraphicsDevice, faisant référence à un QRhi déjà existant, est défini, il n'y aura pas de nouvel objet QRhi dédié créé dans initialize().

Cette fonction a été introduite dans Qt 6.0.

Voir aussi QQuickRenderTarget, QQuickGraphicsDevice, et QQuickGraphicsConfiguration::preferredInstanceExtensions().

void QQuickRenderControl::invalidate()

Arrêter le rendu et libérer les ressources.

C'est l'équivalent des opérations de nettoyage qui se produisent sur un vrai site QQuickWindow lorsque la fenêtre devient cachée.

Cette fonction est appelée par le destructeur. Il n'est donc généralement pas nécessaire de l'appeler directement.

Une fois que la fonction invalidate() a été appelée, il est possible de réutiliser l'instance QQuickRenderControl en appelant à nouveau la fonction initialize().

Note : Cette fonction ne prend pas en compte QQuickWindow::persistentSceneGraph() ou QQuickWindow::persistentGraphics(). Cela signifie que les ressources spécifiques au contexte sont toujours libérées.

void QQuickRenderControl::polishItems()

Cette fonction doit être appelée le plus tard possible avant sync(). Dans le cas d'un scénario threadé, le rendu peut se faire en parallèle avec cette fonction.

void QQuickRenderControl::prepareThread(QThread *targetThread)

Prépare le rendu de la scène Qt Quick en dehors du fil d'exécution de l'interface graphique.

targetThread spécifie le thread sur lequel la synchronisation et le rendu auront lieu. Il n'est pas nécessaire d'appeler cette fonction dans un scénario à un seul thread.

void QQuickRenderControl::render()

Rend le graphe de scène en utilisant le contexte actuel.

[signal] void QQuickRenderControl::renderRequested()

Ce signal est émis lorsque le graphe de scène doit être rendu. Il n'est pas nécessaire d'appeler sync().

Note : Evitez de déclencher le rendu directement lorsque ce signal est émis. Préférez plutôt le différer en utilisant un timer par exemple. Cela permettra d'obtenir de meilleures performances.

[virtual] QWindow *QQuickRenderControl::renderWindow(QPoint *offset)

Réimplémenté dans les sous-classes pour renvoyer la fenêtre réelle dans laquelle le contrôle de rendu effectue le rendu.

Si offset n'est pas nul, il est défini sur le décalage du contrôle dans la fenêtre.

Remarque : bien qu'elle ne soit pas obligatoire, la réimplémentation de cette fonction devient essentielle pour la prise en charge de plusieurs écrans ayant des rapports de pixels différents et pour le positionnement correct des fenêtres contextuelles ouvertes à partir de QML. Il est donc fortement recommandé de la fournir dans les sous-classes.

[static] QWindow *QQuickRenderControl::renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr)

Renvoie la fenêtre réelle dans laquelle win est rendu, s'il y en a une.

Si offset n'est pas nul, il prend la valeur du décalage du rendu à l'intérieur de sa fenêtre.

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

Renvoie l'adresse QRhi à laquelle QQuickRenderControl est associé.

Remarque : QRhi n'existe que lorsque initialize() a été exécuté avec succès. Avant cela, la valeur de retour est nulle.

Remarque : Cette fonction n'est pas applicable et renvoie une valeur nulle lorsque l'on utilise l'adaptation software de Qt Quick.

Cette fonction a été introduite dans Qt 6.6.

Voir aussi commandBuffer(), beginFrame(), et endFrame().

[since 6.0] int QQuickRenderControl::samples() const

Renvoie le nombre d'échantillons actuel. 1 ou 0 signifie qu'il n'y a pas de multi-échantillonnage.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi setSamples().

[signal] void QQuickRenderControl::sceneChanged()

Ce signal est émis lorsque le graphe de la scène est mis à jour, ce qui signifie que polishItems() et sync() doivent être appelés. Si sync() renvoie vrai, alors render() doit être appelé.

Remarque : évitez de déclencher le polissage, la synchronisation et le rendu directement lorsque ce signal est émis. Préférez plutôt les différer en utilisant un timer par exemple. Cela permettra d'obtenir de meilleures performances.

[since 6.0] void QQuickRenderControl::setSamples(int sampleCount)

Définit le nombre d'échantillons à utiliser pour le multi-échantillonnage. Lorsque sampleCount vaut 0 ou 1, le multi-échantillonnage est désactivé.

Remarque : cette fonction est toujours utilisée en combinaison avec une cible de rendu à échantillonnage multiple, ce qui signifie que sampleCount doit correspondre au nombre d'échantillons transmis à QQuickRenderTarget::fromNativeTexture(), qui à son tour doit correspondre au nombre d'échantillons de la texture native.

Cette fonction a été introduite dans Qt 6.0.

Voir aussi samples(), initialize(), et QQuickRenderTarget.

bool QQuickRenderControl::sync()

Cette fonction est utilisée pour synchroniser la scène QML avec le graphe de la scène de rendu.

Si un thread de rendu dédié est utilisé, le thread de l'interface graphique doit être bloqué pendant la durée de cet appel.

Retourne vrai si la synchronisation a modifié le graphe de scène.

[since 6.0] QQuickWindow *QQuickRenderControl::window() const

Renvoie l'adresse QQuickWindow à laquelle cette adresse QQuickRenderControl est associée.

Note : Un QQuickRenderControl est associé à un QQuickWindow lors de la construction du QQuickWindow. La valeur de retour de cette fonction est nulle avant ce moment.

Cette fonction a été introduite dans Qt 6.0.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.