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);
}

メンバ関数ドキュメント

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

ウィジェットフラグがf に設定されたparent の子ウィジェットを構築する。

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

デストラクタ。

QRhiWidget::Api QRhiWidget::api() const

現在設定されているグラフィックス API (QRhi backend) を返します。

setApi()も参照してください 。

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

ウィジェットのカラーバッファとして機能するテクスチャを返します。

initialize() とrender() からのみ呼び出す必要があります。

深度ステンシルバッファやQRhiRenderTarget とは異なり、このテクスチャは常に利用可能で、autoRenderTarget の値とは無関係にQRhiWidget によって管理されます。

msaaColorBuffer()、depthStencilBuffer()、renderTarget()、resolveTexture()も参照 。

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

ウィジェットのレンダリングで使用される深度ステンシルバッファを返します。

initialize() とrender() からのみ呼び出す必要があります。

autoRenderTarget がtrue の場合のみ利用可能。それ以外の場合、返される値はnullptr であり、深度ステンシルバッファとQRhiTextureRenderTarget を作成し管理するのはinitialize() の再実装次第です。

colorTexture() およびrenderTarget()も参照してください 。

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

再実装：QWidget::event(QEvent *event)。

[signal] void QRhiWidget::frameSubmitted()

このシグナルは、ウィジェットのトップレベルウィンドウがコンポジションを終了し、submitted a frame 。

QImage QRhiWidget::grabFramebuffer() const

新しいフレームをレンダリングし、テクスチャの内容を読み返して、QImage として返します。

エラーが発生すると、NULLQImage が返されます。

返されるQImage のフォーマットは、colorBufferFormat() に応じて、QImage::Format_RGBA8888 、QImage::Format_RGBA16FPx4 、QImage::Format_RGBA32FPx4 、またはQImage::Format_BGR30 のいずれかです。

QRhiWidget は、レンダラーのブレンドと合成のアプローチを知らないため、出力に RGB カラー値にアルファが事前乗算されているかどうかを知ることができません。したがって、 形式が適切な場合でも、返される 形式に使用されることはない。結果のデータを適切なように解釈するかどうかは、呼び出し側次第である。_Premultiplied QImage QImage

この関数は、QOpenGLWidget やQQuickWidget との一貫性を保つため、grabFramebuffer() という名前になっています。QRhiWidget のコンテンツから CPU 側の画像データを取得する唯一の方法ではありません。QRhiWidget やその祖先に対してQWidget::grab() を呼び出すことも機能します（QPixmap を返します）。QImage で直接動作することに加えて、grabFramebuffer() のもう1つの利点は、QWidget の残りのインフラを通過する必要がなく、新しいフレームのレンダリングをすぐにトリガしてリードバックを実行できるため、若干パフォーマンスが高くなる可能性があることです。

setColorBufferFormat()も参照してください 。

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

ウィジェットが初めて初期化されたとき、関連するテクスチャのサイズ、フォーマット、サンプルカウントが変更されたとき、またはQRhi とテクスチャが何らかの理由で変更されたときに呼び出されます。この関数は、render() のレンダリングコードで使用されるグラフィックリソースを維持（未作成の場合は作成、サイズが変更された場合は調整と再構築）することが期待されます。

QRhi 、QRhiTexture 、およびその他の関連オブジェクトに問い合わせるには、rhi （）、colorTexture （）、depthStencilBuffer （）、renderTarget （）を呼び出す。

size ウィジェットサイズが変更されると、QRhi オブジェクト、カラーバッファテクスチャ、および深度ステンシルバッファオブジェクトは、すべて以前と同じインスタンスになります（したがって、ゲッターは同じポインタを返します）。

再実装はまた、QRhi オブジェクトとカラーバッファのテクスチャがこの関数の呼び出しの間に変更されるかもしれないことを準備する必要があります。オブジェクトが異なる特別なケースとして、まだ表示されていないウィジェットでgrabFramebuffer （）を実行し、トップレベルのウィジェット内でウィジェットを画面上に表示する場合があります。この場合、グラブは専用のQRhi 、その後のinitialize()とrender()呼び出しでトップレベル・ウィンドウの関連QRhi に置き換えられます。もう1つの、より一般的なケースは、ウィジェットが新しいトップレベル・ウィンドウに属するように再レンタリングされる場合です。この場合、QRhi と、QRhiWidget によって管理されるすべての関連リソースは、この関数の後続の呼び出しにおいて、以前とは異なるインスタンスになります。そして、サブクラスによって以前に作成されたすべての既存のQRhi リソースは、ウィジェットによってもう使用されるべきではない以前のQRhi に属しているため、破棄されることが重要です。

デフォルトであるautoRenderTarget がtrue の場合、colorTexture() (またはmsaaColorBuffer()) とデプスステンシル・バッファに関連付けられたデプスステンシルQRhiRenderBuffer とQRhiTextureRenderTarget が自動的に作成され、管理されます。initialize()およびrender()の再実装は、depthStencilBuffer()およびrenderTarget()を介して、これらのオブジェクトに問い合わせることができます。autoRenderTarget がfalse に設定されると、これらのオブジェクトは自動的に作成され管理されなくなります。むしろ、initialize() の実装が、適切と思われるようにバッファを作成し、レンダー・ターゲットを設定することになります。レンダー・ターゲットの追加のカラー・アタッチメントやデプス・スタ ン・アタッチメントを手動で管理する場合、それらのサイズとサンプル数は、常にcolorTexture() /msaaColorBuffer() のサイズとサンプル数に従わなければなりません。

サブクラスで作成されたグラフィックリソースは、サブクラスのデストラクタ実装で解放されることが期待されます。

cb は、ウィジェットの現在のフレームに対する です。この関数は、フレームが記録されている状態で呼び出されますが、アクティブなレンダーパスはありません。コマンドバッファは主に、 () に延期することなく をエンキューできるようにするために提供されます。QRhiCommandBuffer render resource updates

render()も参照してください 。

bool QRhiWidget::isDebugLayerEnabled() const

使用中のグラフィックスAPIに適用可能な場合、デバッグまたは検証レイヤが要求される場合はtrueを返します。

setDebugLayerEnabled()も参照 。

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

ウィジェットのマルチサンプルカラーバッファとして機能する renderbuffer を返します。

initialize() とrender() からのみ呼び出されなければならない。

sampleCount が 1 より大きく、マルチサンプル アンチエイリアライズが有効な場合、返されるQRhiRenderBuffer は一致するサンプルカウントを持ち、カラーバッファとして機能します。このバッファへのレンダリングに使用されるグラフィックパイプラインは、同じサンプルカウントで作成されなければならず、デプスステンシルバッファのサンプルカウントも一致しなければなりません。マルチサンプルのコンテンツは、resolveTexture （）から返されるテクスチャに解決されることが期待されます。autoRenderTarget がtrue の場合、renderTarget() は、カラーアタッチメント 0 のrenderbuffer として msaaColorBuffer() を設定し、そのresolveTexture としてresolveTexture() を設定することで、これを行うように自動的に設定されます。

MSAAが使用されていない場合、戻り値はnullptr 。代わりにcolorTexture() を使用してください。

基礎となる 3D グラフィックス API によっては、サンプル数が 1 より大きいマルチサンプルテクスチャとカラーレンダーバッファの間に実用的な違いがない場合があります（QRhi は、両方を同じネイティブリソースタイプにマッピングするだけかもしれません）。しかし、古い API の中には、テクスチャとレンダーバッファを区別するものもあります。マルチサンプルレンダーバッファは利用できるが、マルチサンプルテクスチャは利用できないOpenGL ES 3.0をサポートするために、QRhiWidget 、常にマルチサンプルQRhiRenderBuffer をカラーアタッチメントとして使用してMSAAを実行します（決してマルチサンプルQRhiTexture ）。

colorTexture()、depthStencilBuffer()、renderTarget()、resolveTexture()も参照の こと。

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

再実装：QWidget::paintEvent(QPaintEvent *event)。

ペイントイベントを処理します。

QWidget::update() を呼び出すと、ペイント・イベントe が送信され、この関数が呼び出されます。イベントの送信は非同期で、update() から戻った後のある時点で行われます。この関数は、いくつかの準備の後、仮想render （）を呼び出して、QRhiWidget の関連テクスチャの内容を更新します。その後、ウィジェットのトップレベルウィンドウは、テクスチャをウィンドウの残りの部分と合成します。

[virtual protected] void QRhiWidget::releaseResources()

グラフィックスリソースを早期解放する必要が生じたときに呼び出されます。

これは通常、トップレベルウィジェットの子階層に追加されたQRhiWidget では発生しません。したがって、多くの場合、この関数を再実装する必要はありません。例えば、アプリケーションは単一のトップレベル・ウィジェット（ネイティブ・ウィンドウ）しか持たないからです。しかし、ウィジェット（またはその祖先）の再ペアレントが関係する場合、この関数の再実装は、堅牢でよく書かれたQRhiWidget サブクラスで必要になります。

この関数が呼び出されたとき、実装は、デストラクタでこれを行うことが期待される方法と同様に、すべてのQRhi リソース（QRhiBuffer 、QRhiTexture などのオブジェクト）を破棄することが期待されます。initialize （）は最終的にその後に呼び出されるため、ナルアウト、スマートポインタの使用、resources-invalid フラグの設定も必要になります。ただし、リソースの解放をその後のinitialize() に先送りするのは間違いであることに注意してください。この関数が呼ばれた場合、リターンする前にリソースを削除しなければならない。また、この関数を実装しても、クラスのデストラクタ（またはスマート・ポインタ）を置き換えることはできません。

この関数の動作例については、Cube RHI Widget Exampleを参照してください。そこでは、QRhiWidget を（親ウィジェットを持つことによる）子ウィジェットと（親ウィジェットを持たないことによる）トップレベル・ウィジェットの間で切り替えるボタンが、この関数を呼び出すトリガーとなります。これは、関連するトップレベル・ウィジェット、ネイティブ・ウィンドウ、QRhi がすべて、QRhiWidget のライフタイム中に変更されるためで、以前使用されていたQRhi が破棄されると、まだ生きているQRhiWidget によって管理されている関連リソースが早期に解放されることになります。

この関数が呼び出されるもう1つのケースは、grabFramebuffer （ ）が、可視ウィンドウに追加されていないQRhiWidget 、つまりレンダリングがオフスクリーンで実行されるときに使用される場合である。後でこのQRhiWidget が可視化されたり、可視ウィジェット階層に追加されたりすると、関連するQRhi は、オフスクリーンレンダリングに使用される一時的なものから、ウィンドウ専用のものに変更され、この関数もトリガされます。

initialize()も参照してください 。

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

ウィジェットの内容（テクスチャの内容）の更新が必要なときに呼び出されます。

この関数が呼び出される前に、常にinitialize() が少なくとも 1 回呼び出される。

更新を要求するには、QWidget::update （）を呼び出します。render() 内からupdate() を呼び出すと、vsync によって減速されながら連続的に更新されます。

cb は、ウィジェットの現在のフレームに対する です。この関数は、フレームが記録されている状態で呼び出されますが、アクティブなレンダーパスはありません。QRhiCommandBuffer

initialize()も参照してください 。

[signal] void QRhiWidget::renderFailed()

QRhi このシグナルは、ウィジェットがそのバッキングテクスチャにレンダリングするはずのとき（widget update またはgrabFramebuffer() の呼び出しによる）、いつでも発行されます。

このシグナルは、問題が発生したときに複数回発せられることがあります。このシグナルは1回しか発せられないと思わないでください。エラー処理コードに一度だけ通知する場合は、Qt::SingleShotConnection に接続してください。

[protected] QRhiRenderTarget *QRhiWidget::renderTarget() const

render() の再実装においてQRhiCommandBuffer::beginPass() と共に使用しなければならないレンダーターゲットオブジェクトを返す。

initialize() およびrender() からのみ呼び出されなければならない。

autoRenderTarget がtrue の場合のみ利用可能。それ以外の場合、返される値はnullptr であり、デプスステンシル・バッファとQRhiTextureRenderTarget を作成し管理するのはinitialize() の再実装に任されている。

graphics pipelines を作成する際には、QRhiRenderPassDescriptor が必要である。これは、renderPassDescriptor() を呼び出すことで、返されたQRhiTextureRenderTarget から問い合わせることができる。

colorTexture() およびdepthStencilBuffer()も参照 。

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

再実装：QWidget::resizeEvent(QResizeEvent *event)。

e event パラメータで渡されるリサイズイベントを処理します。仮想関数initialize() を呼び出します。

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

マルチサンプルコンテンツが解決される非マルチサンプルテクスチャを返します。

マルチサンプルアンチエイリアスが有効でない場合、結果はnullptr になります。

initialize() およびrender() からのみ呼び出す必要があります。

MSAA が有効な場合、これは画面上のQWidget コンテンツの残りと合成されるテクスチャです。ただし、QRhiWidget のレンダリングは、msaaColorBuffer （）から返される（マルチサンプルの）QRhiRenderBuffer をターゲットにする必要があります。autoRenderTarget がtrue の場合、これはrenderTarget() から返されるQRhiRenderTarget によって処理される。そうでない場合、カラーバッファと resolve テクスチャの両方を持つレンダーターゲットオブジェクトを正しく設定するのは、サブクラスのコード次第です。

colorTexture()も参照してください 。

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

現在のQRhi オブジェクトを返します。

initialize() およびrender() からのみ呼び出す必要があります。

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

使用するグラフィックス API およびQRhi バックエンドをapi に設定します。

デフォルト値はプラットフォームによって異なります：macOSとiOSではMetal、WindowsではDirect 3D 11、それ以外ではOpenGLです。

api は、ウィジェットとそのトップレベルウィンドウに対して一度だけ設定できます。一旦設定され、有効になると、ウィンドウはそのAPIとQRhi バックエンドのみを使用してレンダリングできます。別の値を設定しようとしたり、別のapi で別のQRhiWidget を追加しようとしても、期待通りに機能しません。

setColorBufferFormat()、setDebugLayerEnabled()、api()も参照して ください。

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

深度ステンシルQRhiRenderBuffer とQRhiTextureRenderTarget がウィジェットによって自動的に作成され、維持されるかどうかを制御します。デフォルト値はtrue です。

自動モードでは、深度ステンシルバッファのサイズとサンプルカウントは、カラーバッファテクスチャの設定に従います。非自動モードでは、renderTarget() とdepthStencilBuffer() は常にnullptr を返し、これらのオブジェクトの設定と管理はinitialize() のアプリケーションの実装に任されます。

自動モードを無効にするには、派生クラスのコンストラクタなど、早い段階でenabled をfalse に設定してこの関数を呼び出します。

void QRhiWidget::setDebugLayerEnabled(bool enable)

enable が true の場合、基礎となるグラフィックス API のデバッグまたは検証レイヤーを要求します。

VulkanとDirect 3Dに適用できます。

デフォルトでは無効になっています。

setApi() およびisDebugLayerEnabled()も参照してください 。