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

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

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()

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

このシグナルは、問題が発生したときに複数回発せられることがあります。このシグナルは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()も参照してください 。