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

parent の子となるウィジェットを作成し、ウィジェットのフラグをf に設定します。

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

デストラクタ。

QRhiWidget::Api QRhiWidget::api() const

現在設定されているグラフィックスAPI（QRhi バックエンド）を返します。

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 として返します。

エラーが発生した場合は、nullのQImage が返されます。

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

QRhiWidget は、レンダラーのブレンディングや合成の処理方法を把握していないため、出力にRGB色値としてアルファ値が事前乗算されているかどうかを判断できません。したがって、たとえ適切である場合でも、返されるQImage に対しては、_Premultiplied やQImage 形式は決して使用されません。結果のデータをどのように再解釈するかは、呼び出し側の判断に委ねられます。

この関数の名前は、QOpenGLWidget およびQQuickWidget との一貫性を保つため、grabFramebuffer()と命名されています。QRhiWidget のコンテンツからCPU側の画像データを取得する方法はこれだけではありません。QRhiWidget またはその祖先オブジェクトに対してQWidget::grab()を呼び出す方法も機能します（QPixmap を返します）。QImage を直接操作できることに加え、grabFramebuffer()のもう一つの利点は、QWidget の残りのインフラストラクチャを経由する必要がなく、すぐに新しいフレームのレンダリングをトリガーして読み出しを行えるため、パフォーマンスが若干向上する可能性があることです。

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

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

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

QRhi 、QRhiTexture 、およびその他の関連オブジェクトを取得するには、rhi()、colorTexture()、depthStencilBuffer()、およびrenderTarget()を呼び出します。

ウィジェットのサイズが変更された場合、QRhi オブジェクト、カラーバッファテクスチャ、および深度・ステンシルバッファオブジェクトはすべて以前と同じインスタンス（つまり、ゲッターは同じポインタを返す）ですが、カラーバッファおよび深度・ステンシルバッファは再構築されている可能性が高く、その結果、size および基盤となるネイティブテクスチャリソースは、前回の呼び出し時とは異なる場合があります。

また、この関数の呼び出し間で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() のサイズとサンプル数に従わなければなりません。そうしないと、レンダリングエラーや 3D API の検証エラーが発生する可能性があります。

サブクラスによって作成されたグラフィックスリソースは、サブクラスのデストラクタの実装内で解放されることが想定されています。

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()はこれを自動的に行うように設定されます。具体的には、msaaColorBuffer()をカラーアタッチメント0のrenderbuffer として、resolveTexture()をそのresolveTexture として設定します。

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

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

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()が最終的に呼び出されるため、スマートポインタを使用してリソースをNULLに設定するか、resources-invalid フラグを設定することも必要となります。 ただし、リソースの解放を後続のinitialize()に委ねることは誤りであることに注意してください。この関数が呼び出された場合、リソースは戻り値を返す前に解放されなければなりません。また、この関数を実装しても、クラスのデストラクタ（またはスマートポインタ）に代わるものではない点にも注意してください。グラフィックリソースは、依然として両方で解放する必要があります。

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

この関数が呼び出されるもう一つのケースは、grabFramebuffer()が、表示中のウィンドウに追加されていないQRhiWidget に対して使用された場合、すなわちレンダリングがオフスクリーンで行われる場合です。 その後、このQRhiWidget が可視化されたり、可視ウィジェット階層に追加されたりすると、関連するQRhi は、オフスクリーンレンダリングに使用されていた一時的なものから、そのウィンドウ専用のものへと変更されるため、この関数も同様に呼び出されます。

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

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

ウィジェットのコンテンツ（つまり、テクスチャの内容）を更新する必要があるときに呼び出されます。

この関数が呼び出される前には、必ず少なくとも1回はinitialize()が呼び出されています。

更新を要求するには、QWidget::update() を呼び出してください。render() 内からupdate() を呼び出すと、vsync によって制御されながら継続的に更新が行われます。

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

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

[signal] void QRhiWidget::renderFailed()

このシグナルは、ウィジェットがバッキングテクスチャにレンダリングを行うべき時（widget update による場合、またはgrabFramebuffer()の呼び出しによる場合）、グラフィック設定に関連する問題などにより、ウィジェットが使用できるQRhi が存在しない場合に発せられます。

問題が発生した場合、このシグナルは複数回発火する可能性があります。1回だけ発火すると想定しないでください。エラー処理コードへの通知を1回のみ行う必要がある場合は、Qt::SingleShotConnection に接続してください。

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

render() の再実装において、QRhiCommandBuffer::beginPass() と併用する必要があるレンダリングターゲットオブジェクトを返します。

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

autoRenderTarget がtrue である場合にのみ利用可能です。それ以外の場合、戻り値はnullptr となり、深度・ステンシルバッファおよびQRhiTextureRenderTarget の作成と管理は、initialize()の再実装に委ねられます。

graphics pipelines を作成する際には、QRhiRenderPassDescriptor が必要です。これは、返されたQRhiTextureRenderTarget に対してrenderPassDescriptor()を呼び出すことで取得できます。

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

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

QWidget::resizeEvent(QResizeEvent *event) を再実装します。

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

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

マルチサンプルコンテンツが解像される、マルチサンプルではないテクスチャを返します。

マルチサンプルアンチエイリアシングが有効になっていない場合、結果はnullptr となります。

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

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

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()も参照してください 。