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 = {})

Construit un widget qui est un enfant de parent, avec les drapeaux de widget fixés à f.

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

Destructeur.

QRhiWidget::Api QRhiWidget::api() const

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

Voir aussi setApi().

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

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

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 QRhiWidget, indépendamment de la valeur de autoRenderTarget.

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

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

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

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

Disponible uniquement si autoRenderTarget est true. Sinon, la valeur renvoyée est nullptr et c'est à 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().

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

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

[signal] void QRhiWidget::frameSubmitted()

Ce signal est émis après que la fenêtre de premier niveau du widget a terminé sa composition et a submitted a frame.

QImage QRhiWidget::grabFramebuffer() const

Rend une nouvelle image, lit le contenu de la texture et le renvoie sous forme de QImage.

En cas d'erreur, une adresse QImage nulle est renvoyée.

L'adresse QImage renvoyée aura un format de QImage::Format_RGBA8888, QImage::Format_RGBA16FPx4, QImage::Format_RGBA32FPx4, ou QImage::Format_BGR30, en fonction de colorBufferFormat().

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

La fonction est nommée grabFramebuffer() par souci de cohérence avec QOpenGLWidget et QQuickWidget. Ce n'est pas la seule façon d'obtenir des données d'image côté CPU à partir du contenu de QRhiWidget: appeler QWidget::grab() sur un QRhiWidget, ou un ancêtre de celui-ci, est également fonctionnel (renvoyant un QPixmap). En plus de travailler 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 et ensuite effectuer la lecture.

Voir aussi setColorBufferFormat().

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

Appelée lorsque le widget 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 QRhi et 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 du widget 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. Un cas particulier où les objets seront différents est celui de l'exécution d'une fonction grabFramebuffer() avec un widget qui n'est pas encore affiché et qui rend le widget visible à l'écran à l'intérieur d'un widget de niveau supérieur. Dans ce cas, la saisie se fera avec un QRhi dédié qui sera ensuite remplacé par le QRhi associé à la fenêtre de niveau supérieur dans les invocations ultérieures de initialize() et render(). Un autre cas, plus courant, est celui où le widget est réparti de manière à appartenir à une nouvelle fenêtre de premier niveau. Dans ce cas, le QRhi et toutes les ressources connexes gérées par le QRhiWidget seront des instances différentes qu'auparavant lors de l'appel ultérieur à 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'ancienne QRhi qui ne doit plus être utilisée par le widget.

Lorsque autoRenderTarget est true, ce qui est le cas par défaut, un crayon de profondeur QRhiRenderBuffer et un QRhiTextureRenderTarget associé à colorTexture() (ou msaaColorBuffer()) et le 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 autoRenderTarget 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() / 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 du widget. 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().

Voir également render().

bool QRhiWidget::isDebugLayerEnabled() const

Retourne true si une couche de débogage ou de validation sera demandée si elle est applicable à l'API graphique utilisée.

Voir aussi setDebugLayerEnabled().

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

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

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

Lorsque sampleCount est plus grand que 1, et que l'antialisation multi-échantillon est activée, 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 autoRenderTarget 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.

Selon l'API graphique 3D sous-jacente, il peut n'y avoir aucune différence pratique entre les textures multi-échantillons 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, QRhiWidget 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().

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

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

Gère les événements de peinture.

L'appel à QWidget::update() entraînera l'envoi d'un événement de peinture e, et donc l'invocation de cette fonction. L'envoi de l'événement est asynchrone et se produit à un moment donné après le retour de update(). Cette fonction appellera ensuite, après une certaine préparation, la fonction virtuelle render() pour mettre à jour le contenu de la texture associée à QRhiWidget. La fenêtre de premier niveau du widget composera alors la texture avec le reste de la fenêtre.

[virtual protected] void QRhiWidget::releaseResources()

Appelé lorsqu'il est nécessaire de libérer les ressources graphiques de manière anticipée.

Normalement, cela ne se produit pas pour un QRhiWidget qui est ajouté à la hiérarchie des enfants d'un widget de premier niveau et qui y reste pour le reste de sa durée de vie et de celle du widget de premier niveau. Dans de nombreux cas, il n'est donc pas nécessaire de réimplémenter cette fonction, par exemple parce que l'application n'a jamais qu'un seul widget de premier niveau (fenêtre native). Cependant, lorsque le reparentage du widget (ou d'un de ses ancêtres) est impliqué, la réimplémentation de cette fonction deviendra nécessaire dans les sous-classes robustes et bien écrites de QRhiWidget.

Lorsque cette fonction est appelée, l'implémentation est censée détruire toutes les ressources QRhi (objetsQRhiBuffer, QRhiTexture, etc.), de la même manière qu'elle est censée le faire dans le destructeur. L'annulation, l'utilisation d'un pointeur intelligent ou la mise en place d'un drapeau resources-invalid seront également nécessaires, car initialize() sera appelé par la suite. Notez cependant qu'il est erroné de reporter la libération des ressources à la fonction initialize(). Si cette fonction est appelée, la ressource doit être libérée avant de revenir. Notez également que l'implémentation de cette fonction ne remplace pas le destructeur de classe (ou les pointeurs intelligents) : les ressources graphiques doivent toujours être libérées dans les deux cas.

Voir l'exemple de widget Cube RHI pour un exemple de cette fonction en action. Ici, le bouton qui fait basculer le site QRhiWidget entre le statut de widget enfant (en raison de la présence d'un widget parent) et celui de widget de niveau supérieur (en raison de l'absence de widget parent) déclenchera l'invocation de cette fonction puisque le widget de niveau supérieur associé, la fenêtre native et le site QRhi changent tous au cours de la durée de vie du site QRhiWidget, le site QRhi précédemment utilisé étant détruit, ce qui implique une libération anticipée des ressources associées gérées par le site QRhiWidget toujours en vie.

Un autre cas où cette fonction est appelée est lorsque grabFramebuffer() est utilisé 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, ce QRhiWidget est rendu visible ou ajouté à une hiérarchie de widgets visibles, le 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(). Appeler update() à partir de render() conduira à une mise à jour continue, ralentie par vsync.

cb est l'adresse QRhiCommandBuffer pour le cadre actuel 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 d'arrière-plan (soit en raison d'un widget update, soit en raison d'un appel à grabFramebuffer()), mais qu'il n'y a pas de QRhi à utiliser 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 supposez pas qu'il n'est émis qu'une seule fois. Connectez-vous à 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 QRhiCommandBuffer::beginPass() dans les réimplémentations de render().

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

Disponible uniquement si 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 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 aussi 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 qui sont passés dans le paramètre e event. Appelle la fonction virtuelle initialize().

[protected] QRhiTexture *QRhiWidget::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 qui est composée avec le reste du contenu de QWidget à l'écran. Cependant, le rendu de QRhiWidget doit cibler le (multi-échantillon) QRhiRenderBuffer renvoyé par msaaColorBuffer(). Lorsque autoRenderTarget 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 *QRhiWidget::rhi() const

Renvoie l'objet actuel QRhi.

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

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

Définit l'API graphique et le backend QRhi à utiliser pour api.

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

La valeur api ne peut être définie qu'une seule fois pour le widget et sa fenêtre de premier niveau. Une fois la valeur définie et prise en compte, la fenêtre ne peut utiliser que cette API et le backend QRhi pour le rendu. Toute tentative de définir une autre valeur ou d'ajouter un autre QRhiWidget avec un api différent ne fonctionnera pas comme prévu.

Voir aussi setColorBufferFormat(), setDebugLayerEnabled(), et api().

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

Contrôle si un crayon de profondeur QRhiRenderBuffer et un QRhiTextureRenderTarget sont créés et maintenus automatiquement par le widget. La valeur par défaut est true.

En mode automatique, la taille et le nombre d'échantillons du tampon du pochoir de profondeur suivent les paramètres de la texture du tampon de couleur. En mode non automatique, renderTarget() et depthStencilBuffer() renvoient toujours nullptr et c'est alors à l'implémentation de initialize() de l'application de s'occuper de la configuration et de la gestion de ces objets.

Appelez cette fonction avec enabled fixé à false dès le début, par exemple dans le constructeur de la classe dérivée, pour désactiver le mode automatique.

void QRhiWidget::setDebugLayerEnabled(bool enable)

Demande la couche de débogage ou de validation de l'API graphique sous-jacente lorsque enable est vrai.

Applicable pour Vulkan et Direct 3D.

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

Voir aussi setApi() et isDebugLayerEnabled().