QRhiWidget Class

class ExampleRhiWidget : public QRhiWidget
{
public:
    ExampleRhiWidget(QWidget *parent = nullptr) : QRhiWidget(parent) { }
    void initialize(QRhiCommandBuffer *cb) override;
    void render(QRhiCommandBuffer *cb) override;
private:
    QRhi *m_rhi = nullptr;
    std::unique_ptr<QRhiBuffer> m_vbuf;
    std::unique_ptr<QRhiBuffer> m_ubuf;
    std::unique_ptr<QRhiShaderResourceBindings> m_srb;
    std::unique_ptr<QRhiGraphicsPipeline> m_pipeline;
    QMatrix4x4 m_viewProjection;
    float m_rotation = 0.0f;
};

float vertexData[] = {
     0.0f,   0.5f,     1.0f, 0.0f, 0.0f,
    -0.5f,  -0.5f,     0.0f, 1.0f, 0.0f,
     0.5f,  -0.5f,     0.0f, 0.0f, 1.0f,
};

QShader getShader(const QString &name)
{
    QFile f(name);
    return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader();
}

void ExampleRhiWidget::initialize(QRhiCommandBuffer *cb)
{
    if (m_rhi != rhi()) {
        m_pipeline.reset();
        m_rhi = rhi();
    }

    if (!m_pipeline) {
        m_vbuf.reset(m_rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData)));
        m_vbuf->create();

        m_ubuf.reset(m_rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 64));
        m_ubuf->create();

        m_srb.reset(m_rhi->newShaderResourceBindings());
        m_srb->setBindings({
            QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, m_ubuf.get()),
        });
        m_srb->create();

        m_pipeline.reset(m_rhi->newGraphicsPipeline());
        m_pipeline->setShaderStages({
            { QRhiShaderStage::Vertex, getShader(QLatin1String(":/shader_assets/color.vert.qsb")) },
            { QRhiShaderStage::Fragment, getShader(QLatin1String(":/shader_assets/color.frag.qsb")) }
        });
        QRhiVertexInputLayout inputLayout;
        inputLayout.setBindings({
            { 5 * sizeof(float) }
        });
        inputLayout.setAttributes({
            { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
            { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
        });
        m_pipeline->setVertexInputLayout(inputLayout);
        m_pipeline->setShaderResourceBindings(m_srb.get());
        m_pipeline->setRenderPassDescriptor(renderTarget()->renderPassDescriptor());
        m_pipeline->create();

        QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
        resourceUpdates->uploadStaticBuffer(m_vbuf.get(), vertexData);
        cb->resourceUpdate(resourceUpdates);
    }

    const QSize outputSize = colorTexture()->pixelSize();
    m_viewProjection = m_rhi->clipSpaceCorrMatrix();
    m_viewProjection.perspective(45.0f, outputSize.width() / (float) outputSize.height(), 0.01f, 1000.0f);
    m_viewProjection.translate(0, 0, -4);
}

void ExampleRhiWidget::render(QRhiCommandBuffer *cb)
{
    QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
    m_rotation += 1.0f;
    QMatrix4x4 modelViewProjection = m_viewProjection;
    modelViewProjection.rotate(m_rotation, 0, 1, 0);
    resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData());

    const QColor clearColor = QColor::fromRgbF(0.4f, 0.7f, 0.0f, 1.0f);
    cb->beginPass(renderTarget(), clearColor, { 1.0f, 0 }, resourceUpdates);

    cb->setGraphicsPipeline(m_pipeline.get());
    const QSize outputSize = colorTexture()->pixelSize();
    cb->setViewport(QRhiViewport(0, 0, outputSize.width(), outputSize.height()));
    cb->setShaderResources();
    const QRhiCommandBuffer::VertexInput vbufBinding(m_vbuf.get(), 0);
    cb->setVertexInput(0, 1, &vbufBinding);
    cb->draw(3);

    cb->endPass();

    update();
}

#version 440
layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;
layout(location = 0) out vec3 v_color;
layout(std140, binding = 0) uniform buf {
    mat4 mvp;
};

void main()
{
    v_color = color;
    gl_Position = mvp * position;
}

#version 440
layout(location = 0) in vec3 v_color;
layout(location = 0) out vec4 fragColor;

void main()
{
    fragColor = vec4(v_color, 1.0);
}

Documentation des fonctions membres

[explicit] QRhiWidget::QRhiWidget(QWidget *parent = nullptr, Qt::WindowFlags f = {})

Crée un widget qui est un enfant de ` parent`, avec les indicateurs de widget définis sur ` f`.

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

Destructeur.

QRhiWidget::Api QRhiWidget::api() const

Renvoie l'API graphique actuellement définie (backend «QRhi »).

Voir aussi setApi().

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

Renvoie la texture servant de tampon de couleur pour le widget.

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 ` QRhiWidget`, quelle que soit la valeur de ` autoRenderTarget`.

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

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

Renvoie le tampon de profondeur-stencil utilisé par le rendu du widget.

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

Disponible uniquement lorsque autoRenderTarget 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 ainsi qu’un QRhiTextureRenderTarget.

Voir également colorTexture() et renderTarget().

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

Réimplémente : ` QWidget::event(QEvent *event)`.

[signal] void QRhiWidget::frameSubmitted()

Ce signal est émis une fois que la fenêtre de niveau supérieur du widget a terminé sa composition et qu'elle a atteint l'ét submitted a frame.

QImage QRhiWidget::grabFramebuffer() const

Affiche une nouvelle image, relit le contenu de la texture et le renvoie sous la forme d'un objet ` QImage`.

En cas d’erreur, une instance ` QImage ` nulle est renvoyée.

L’ QImage renvoyé aura un format de type « QImage::Format_RGBA8888 », « QImage::Format_RGBA16FPx4 », « QImage::Format_RGBA32FPx4 » ou « QImage::Format_BGR30 », selon la fonction « colorBufferFormat() ».

QRhiWidget ne connaît pas l’approche du moteur de rendu en matière de fusion et de composition, et ne peut donc pas savoir si la sortie comporte une alpha pré-multipliée dans les valeurs de couleur RVB. Ainsi, les formats _Premultiplied et QImage ne sont jamais utilisés pour la valeur QImage renvoyée, même lorsque cela serait approprié. Il appartient à l’appelant de réinterpréter les données résultantes comme il le juge bon.

La fonction est nommée `grabFramebuffer()` par souci de cohérence avec ` QOpenGLWidget ` et ` QQuickWidget`. Ce n’est pas le seul moyen d’extraire des données d’image côté CPU à partir du contenu de ` QRhiWidget` : l’appel de ` QWidget::grab()` sur un ` QRhiWidget`, ou l’un de ses ancêtres, fonctionne également (renvoyant un ` QPixmap`). Outre le fait de fonctionner directement avec QImage, un autre avantage de grabFramebuffer() est qu’il peut être légèrement plus performant, simplement parce qu’il n’a pas besoin de passer par le reste de l’infrastructure QWidget mais peut immédiatement déclencher le rendu d’une nouvelle image, puis effectuer la lecture.

Voir également setColorBufferFormat().

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

Appelée lors de la première initialisation du widget, lorsque la taille, le format ou le nombre d’échantillons de la texture associée change, ou lorsque l’ QRhi et 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, l'QRhiTexture et d'autres objets associés, appelez rhi(), colorTexture(), depthStencilBuffer() et renderTarget().

Lorsque la taille du widget change, l’objet ` QRhi `, la texture du tampon de couleur et les objets des tampons de profondeur et 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. Un cas particulier où les objets seront différents se produit lorsqu’on effectue un ` grabFramebuffer()` avec un widget qui n’est pas encore affiché, puis qu’on rend ce widget visible à l’écran au sein d’un widget de niveau supérieur. Dans ce cas, la capture s’effectuera avec une ` QRhi ` dédiée, qui sera ensuite remplacée par la ` QRhi ` associée à la fenêtre de niveau supérieur lors des appels suivants à `initialize()` et ` render()`. Un autre cas, plus courant, se produit lorsque le widget est réaffecté à une nouvelle fenêtre de niveau supérieur. Dans ce cas, l’instance ` QRhi ` et toutes les ressources associées gérées par l’instance ` QRhiWidget ` 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 existantes de type ` QRhi ` créées précédemment par la sous-classe soient détruites, car elles appartiennent à l’instance ` QRhi ` précédente qui ne doit plus être utilisée par le widget.

Lorsque ` autoRenderTarget ` est défini sur ` true` (ce qui est la 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 ` autoRenderTarget ` est défini sur ` false`, ces objets ne sont plus créés ni gérés automatiquement. C’est alors à l’implémentation de la fonction `initialize()` qu’il reviendra 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()` / ` msaaColorBuffer()`, sous peine de provoquer des erreurs de rendu ou de validation de l’API 3D.

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 pour l’image courante du widget. 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().

Voir également ` render()` ().

bool QRhiWidget::isDebugLayerEnabled() const

Renvoie « true » si une couche de débogage ou de validation sera sollicitée, le cas échéant, pour l'API graphique utilisée.

Voir également setDebugLayerEnabled().

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

Renvoie le tampon de rendu servant de tampon de couleur multi-échantillonnage pour le widget.

Ne doit être appelée 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 multi-échantillon doit être résolu dans la texture renvoyée par la fonction ` resolveTexture()`. Lorsque ` autoRenderTarget ` 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. Il convient alors d’utiliser 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, QRhiWidget 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().

[override virtual protected] void QRhiWidget::paintEvent(QPaintEvent *e)

Réimplémente : ` QWidget::paintEvent(QPaintEvent *event)`.

Gère les événements de dessin.

L'appel de ` QWidget::update()` entraîne l'envoi d'un événement de dessin ` e`, ce qui provoque l'appel de cette fonction. L'envoi de l'événement est asynchrone et se produira à un moment donné après le retour de ` update()`. Cette fonction appellera alors, après quelques préparatifs, la fonction virtuelle ` render()` pour mettre à jour le contenu de la texture associée au ` QRhiWidget`. La fenêtre de niveau supérieur du widget effectuera ensuite la composition de la texture avec le reste de la fenêtre.

[virtual protected] void QRhiWidget::releaseResources()

Appelée lorsqu'il est nécessaire de libérer prématurément les ressources graphiques.

Cela ne se produit généralement pas pour un « QRhiWidget » ajouté à la hiérarchie des enfants d’un widget de niveau supérieur, car il y reste alors jusqu’à la fin de sa durée de vie et de celle du widget de niveau supérieur. Ainsi, dans de nombreux cas, il n’est pas nécessaire de réimplémenter cette fonction, par exemple parce que l’application ne comporte qu’un seul widget de niveau supérieur (fenêtre native). Cependant, en cas de changement de parent du widget (ou d’un de ses ancêtres), la réimplémentation de cette fonction deviendra nécessaire dans des sous-classes d’ QRhiWidget s robustes et bien écrites.

Lorsque cette fonction est appelée, l’implémentation doit détruire toutes les ressources de type ` QRhi ` (objets `QRhiBuffer`, ` QRhiTexture`, etc.), de la même manière qu’elle est censée le faire dans le destructeur. Il sera également nécessaire de mettre à zéro les pointeurs, d’utiliser un pointeur intelligent ou de définir un indicateur « resources-invalid », car la fonction ` initialize()` finira par être appelée par la suite. Notez toutefois qu’il est incorrect de reporter la libération des ressources à l’appel ultérieur de ` initialize()`. Si cette fonction est appelée, la ressource doit être libérée avant le retour. Notez également que l’implémentation de cette fonction ne remplace pas le destructeur de la classe (ni les pointeurs intelligents) : les ressources graphiques doivent toujours être libérées dans les deux cas.

Consultez l’exemple du widget Cube RHI pour voir cela en action. Dans cet exemple, le bouton qui fait basculer l’ QRhiWidget entre le statut de widget enfant (lorsqu’il possède un widget parent) et celui de widget de niveau supérieur (lorsqu’il n’a pas de widget parent) déclenchera l’appel de cette fonction, car le widget de niveau supérieur associé, la fenêtre native, et l’ QRhi changent tous au cours du cycle de vie de l’ QRhiWidget, l’ QRhi précédemment utilisé étant détruit, ce qui implique une libération anticipée des ressources associées gérées par l’ QRhiWidget toujours actif.

Cette fonction est également appelée lorsque ` grabFramebuffer()` est utilisée avec un ` QRhiWidget ` qui n’est pas ajouté à une fenêtre visible, c’est-à-dire que le rendu est effectué hors écran. Si, par la suite, cet QRhiWidget est rendu visible ou ajouté à une hiérarchie de widgets visible, l’ QRhi associé passera de celui utilisé temporairement pour le rendu hors écran à celui dédié à la fenêtre, ce qui déclenchera également cette fonction.

Voir également initialize().

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

Appelée lorsque le contenu du widget (c'est-à-dire le contenu de la texture) 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 ` QWidget::update()`. L'appel de ` update()` depuis l'intérieur de `render()` entraînera une mise à jour continue, limitée par la synchronisation verticale (vsync).

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

Voir également initialize().

[signal] void QRhiWidget::renderFailed()

Ce signal est émis chaque fois que le widget est censé effectuer un rendu sur sa texture de support (soit à la suite d’un appel à ` widget update `, soit à la suite d’un appel à ` grabFramebuffer()`), mais qu’aucune texture de support ( QRhi ) n’est disponible pour le widget, probablement en raison de problèmes liés à la configuration graphique.

Ce signal peut être émis plusieurs fois lorsqu’un problème survient. Ne partez pas du principe qu’il n’est émis qu’une seule fois. Utilisez ` Qt::SingleShotConnection ` si le code de gestion des erreurs ne doit être notifié qu’une seule fois.

[protected] QRhiRenderTarget *QRhiWidget::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ée qu’à partir de ` initialize()` et ` render()`.

Disponible uniquement lorsque autoRenderTarget 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 ainsi qu’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() et depthStencilBuffer().

[override virtual protected] void QRhiWidget::resizeEvent(QResizeEvent *e)

Réimplémente : QWidget::resizeEvent(QResizeEvent *event).

Gère les événements de redimensionnement transmis via le paramètre d'événement e. Appelle la fonction virtuelle initialize().

[protected] QRhiTexture *QRhiWidget::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ée qu’à partir de ` initialize()` et ` render()`.

Lorsque le MSAA est activé, il s’agit de la texture qui est composée avec le reste du contenu de l’ QWidget à l’écran. Cependant, le rendu de QRhiWidget doit cibler l’ QRhiRenderBuffer (multi-échantillon) renvoyée par msaaColorBuffer(). Lorsque autoRenderTarget est true, cela est géré par l’ QRhiRenderTarget renvoyée par renderTarget(). Sinon, il appartient au code de la sous-classe de configurer correctement un objet cible de rendu avec à la fois le tampon de couleur et les textures de résolution.

Voir également colorTexture().

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

Renvoie l'objet ` QRhi ` actuel.

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

void QRhiWidget::setApi(QRhiWidget::Api api)

Définit l'API graphique et le backend d'QRhi ation à utiliser sur api.

La valeur par défaut dépend de la plateforme : Metal sur macOS et iOS, Direct 3D 11 sur Windows, OpenGL dans les autres cas.

L’ api ne peut être définie qu’une seule fois pour le widget et sa fenêtre de niveau supérieur ; une fois cette opération effectuée et prise en compte, la fenêtre ne peut utiliser que cette API et ce backend QRhi pour le rendu. Tenter de définir une autre valeur ou d’ajouter une autre QRhiWidget avec une api différente ne fonctionnera pas comme prévu.

Voir également setColorBufferFormat(), setDebugLayerEnabled() et api().

[protected] void QRhiWidget::setAutoRenderTarget(bool enabled)

Détermine si le widget crée et gère automatiquement un tampon de profondeur-stencil ( QRhiRenderBuffer ) et un tampon de texture de couleur ( QRhiTextureRenderTarget ). La valeur par défaut est « true ».

En mode automatique, la taille et le nombre d’échantillons du tampon de profondeur-stencil suivent les paramètres de la texture du tampon de couleur. En mode non automatique, les fonctions ` renderTarget()` et ` depthStencilBuffer()` renvoient toujours ` nullptr ` ; il appartient alors à l’implémentation de la fonction ` initialize()` de l’application de se charger de la configuration et de la gestion de ces objets.

Appelez cette fonction en définissant enabled sur false dès le début, par exemple dans le constructeur de la classe dérivée, afin de désactiver le mode automatique.

void QRhiWidget::setDebugLayerEnabled(bool enable)

Appelle la couche de débogage ou de validation de l'API graphique sous-jacente lorsque la valeur de « enable » est « true ».

Applicable à Vulkan et Direct 3D.

Par défaut, cette fonction est désactivée.

Voir également ` setApi()` et ` isDebugLayerEnabled()`.