QQuickRenderControl Class

Documentation des fonctions membres

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

Crée un objet `QQuickRenderControl`, dont l'objet parent est ` 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 trame graphique. Les appels aux fonctions ` sync()` ou ` render()` doivent être encadrés par des appels aux fonctions `beginFrame()` et ` endFrame()`.

Contrairement à l’environnement Qt 5 antérieur, exclusivement basé sur OpenGL, le rendu avec d’autres API graphiques nécessite des points de début et de fin de trame mieux définis. Lorsque la boucle de rendu est pilotée manuellement via ` QQuickRenderControl`, il incombe désormais à l’utilisateur de ` QQuickRenderControl ` de spécifier ces points.

Une étape de mise à jour typique, incluant l’initialisation du rendu dans une texture existante, pourrait se présenter comme suit. L’extrait de code ci-dessous suppose l’utilisation de 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 transmises au contexte de périphérique à cet endroit

Cette fonction a été introduite dans Qt 6.0.

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

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

Renvoie le tampon de commandes actuel.

Une fois la fonction beginFrame() appelée, un objet ` QRhiCommandBuffer ` est automatiquement créé. Il s'agit du tampon de commande Qt Quick utilisé par le scenegraph, mais dans certains cas, les applications peuvent également souhaiter l'interroger, par exemple pour effectuer des mises à jour de ressources (comme la relecture d'une texture).

La référence au tampon de commandes renvoyée ne doit être utilisée qu’entre les appels à ` beginFrame()` et ` endFrame()`. Il existe toutefois des exceptions spécifiques : par exemple, l’appel à ` lastCompletedGpuTime()` sur le tampon de commandes immédiatement après ` endFrame()`, mais avant le prochain appel à ` beginFrame()`, est valide.

Cette fonction a été introduite dans Qt 6.6.

Voir également rhi(), beginFrame() et endFrame().

[since 6.0] void QQuickRenderControl::endFrame()

Spécifie la fin d'une trame graphique. Les appels à ` sync()` ou ` render()` doivent être encadrés par des appels à ` beginFrame()` et `endFrame()`.

Lorsque cette fonction est appelée, toutes les commandes graphiques mises en file d’attente par l’arborescence de scène sont soumises au contexte ou à la file d’attente de commandes, selon le cas.

Cette fonction a été introduite dans Qt 6.0.

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

[since 6.0] bool QQuickRenderControl::initialize()

Initialise les ressources du graphe de scène. Lorsque vous utilisez une API graphique, telle que Vulkan, Metal, OpenGL ou Direct3D, pour le rendu d’ Qt Quick, QQuickRenderControl configurera un moteur de rendu adapté lors de l’appel de cette fonction. Cette infrastructure de rendu existe tant que l’ QQuickRenderControl existe.

Pour contrôler l’API graphique utilisée par ` Qt Quick `, appelez ` QQuickWindow::setGraphicsApi()` avec l’une des constantes ` QSGRendererInterface:GraphicsApi`. Cette opération doit être effectuée avant d’appeler cette fonction.

Pour empêcher le graphe de scène de créer ses propres objets de périphérique et de contexte, spécifiez un ` QQuickGraphicsDevice` approprié, encapsulant des objets graphiques existants, en appelant ` QQuickWindow::setGraphicsDevice()`.

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

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

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 produirait avec un ` QQuickWindow ` à l’écran si ` QQuickRenderControl ` n’était pas utilisé. Pour que ce nouvel objet ` QRhi ` adopte une ressource de périphérique ou de contexte existante (par exemple, utiliser un ` QOpenGLContext ` existant au lieu d’en créer un nouveau), utilisez ` QQuickWindow::setGraphicsDevice()` comme mentionné ci-dessus. Lorsque l’application souhaite que le rendu de l’ 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, aucun nouvel objet QRhi dédié n’est créé dans initialize().

Cette fonction a été introduite dans Qt 6.0.

Voir également QQuickRenderTarget, QQuickGraphicsDevice et QQuickGraphicsConfiguration::preferredInstanceExtensions().

void QQuickRenderControl::invalidate()

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

Cela équivaut aux opérations de nettoyage qui ont lieu avec une véritable QQuickWindow lorsque la fenêtre est masquée.

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

Une fois invalidate() appelée, il est possible de réutiliser l’instance d’ QQuickRenderControl en appelant à nouveau initialize().

void QQuickRenderControl::polishItems()

Cette fonction doit être appelée le plus tard possible avant l'appel de ` sync()`. Dans un environnement multithread, le rendu peut s'effectuer en parallèle avec cette fonction.

void QQuickRenderControl::prepareThread(QThread *targetThread)

Prépare le rendu de la scène Qt Quick en dehors du thread 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 à thread unique.

void QQuickRenderControl::render()

Effectue le rendu du graphe de scène à l'aide du 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 la fonction ` sync()`.

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

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

Si ` offset ` est non nul, il est défini sur le décalage du contrôle à l'intérieur de la fenêtre.

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

Renvoie la fenêtre réelle dans laquelle win est affiché, le cas échéant.

Si offset n’est pas nul, cette propriété est définie sur le décalage du rendu à l’intérieur de sa fenêtre.

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

Renvoie l'QRhi e auquel ce QQuickRenderControl est associé.

Cette fonction a été introduite dans Qt 6.6.

Voir également commandBuffer(), beginFrame() et endFrame().

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

Renvoie le nombre d'échantillons actuel. La valeur 1 ou 0 indique l'absence 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 scène est mis à jour, ce qui signifie qu’il faut appeler les fonctions ` polishItems()` et ` sync()`. Si la fonction ` sync()` renvoie `true`, il faut alors appeler la fonction ` render()`.

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

Définit le nombre d'échantillons à utiliser pour le multisampling. Lorsque la valeur de ` sampleCount ` est égale à 0 ou 1, le multisampling est désactivé.

Cette fonction a été introduite dans Qt 6.0.

Voir également samples(), initialize() et QQuickRenderTarget.

bool QQuickRenderControl::sync()

Cette fonction sert à synchroniser la scène QML avec le graphe de rendu.

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

Renvoie « true » si la synchronisation a modifié le graphe de scène.

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

Renvoie l'QQuickWindow auquel cet QQuickRenderControl est associé.

Cette fonction a été introduite dans Qt 6.0.