QRhiResourceUpdateBatch Class

メンバ関数のドキュメント

void QRhiResourceUpdateBatch::copyTexture(QRhiTexture *dst, QRhiTexture *src, const QRhiTextureCopyDescription &desc = QRhiTextureCopyDescription())

desc に記載されている通り、src からdst へのテクスチャ間コピー操作をキューに登録します。

void QRhiResourceUpdateBatch::generateMips(QRhiTexture *tex)

指定されたテクスチャtex に対して、ミップマップ生成操作をキューに登録します。

2D およびキューブテクスチャがサポートされています。1D および 3D テクスチャは、それぞれ `QRhi::OneDimensionalTextureMipmaps ` または `QRhi::ThreeDimensionalTextureMipmaps ` 機能がサポートされていると報告されている場合にサポートされます。

bool QRhiResourceUpdateBatch::hasOptimalCapacity() const

このバッチにキューに入れられたバッファおよびテクスチャ操作の数が、妥当な制限値を下回るまで、trueを返します。

このバッチに追加されたバッファおよび／またはテクスチャ操作の数が、特定の制限に達した、または達しようとしている場合、戻り値は false になります。その後もバッチは完全に機能しますが、追加のメモリを割り当てる必要がある場合があります。 したがって、フレームの準備時に多数のバッファおよびテクスチャの更新を単一のバッチに集約するレンダラーでは、この関数が false を返した際に、submitting the batch およびstarting a new one の使用を検討するとよいでしょう。

void QRhiResourceUpdateBatch::merge(QRhiResourceUpdateBatch *other)

「other 」バッチから、キューに登録されているすべての操作をこのバッチにコピーします。

これにより、初期化ステップの段階で既に判明しているリソースの更新情報を1つのバッチにまとめ、後で最初のレンダリングパスを開始する際に別のバッチにマージするという、便利な処理が可能になります：

void init()
{
    initialUpdates = rhi->nextResourceUpdateBatch();
    initialUpdates->uploadStaticBuffer(vbuf, vertexData);
    initialUpdates->uploadStaticBuffer(ibuf, indexData);
    // ...
}

void render()
{
    QRhiResourceUpdateBatch *resUpdates = rhi->nextResourceUpdateBatch();
    if (initialUpdates) {
        resUpdates->merge(initialUpdates);
        initialUpdates->release();
        initialUpdates = nullptr;
    }
    // resUpdates->updateDynamicBuffer(...);
    cb->beginPass(rt, clearCol, clearDs, resUpdates);
}

void QRhiResourceUpdateBatch::readBackBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, QRhiReadbackResult *result)

QRhiBuffer の特定の領域の読み取りをキューに登録します。buf 。領域のサイズはsize でバイト単位で指定され、offset は読み取りを開始するオフセット（バイト単位）です。

読み出しは非同期で行われます。result には、操作が完了した際に呼び出されるコールバックが含まれています。データはQRhiReadbackResult::data に格納されます。正常に完了した場合、QByteArray のサイズはsize と等しくなります。失敗した場合は、QByteArray は空になります。

readBackTexture()、QRhi::isFeatureSupported()、およびQRhi::resourceLimit()も参照してください 。

void QRhiResourceUpdateBatch::readBackTexture(const QRhiReadbackDescription &rb, QRhiReadbackResult *result)

rb に記載されているとおり、テクスチャからホストへのコピー操作をキューに登録します。

通常、rb では、ソースとしてQRhiTexture が指定されます。ただし、現在のフレームのスワップチェーンがQRhiSwapChain::UsedAsTransferSource で作成された場合は、そのスワップチェーンがリードバックのソースとなることもあります。この場合、rb において、テクスチャを null のままにしておきます。

他の操作とは異なり、ここでの結果はアプリケーション側で処理する必要があります。そのため、result はデータだけでなく、バッチに対する操作が本質的に非同期であることから、コールバックも提供します:

rhi->beginFrame(swapchain);
cb->beginPass(swapchain->currentFrameRenderTarget(), colorClear, dsClear);
// ...
QRhiReadbackResult *rbResult = new QRhiReadbackResult;
rbResult->completed = [rbResult] {
    {
        const QImage::Format fmt = QImage::Format_RGBA8888_Premultiplied; // fits QRhiTexture::RGBA8
        const uchar *p = reinterpret_cast<const uchar *>(rbResult->data.constData());
        QImage image(p, rbResult->pixelSize.width(), rbResult->pixelSize.height(), fmt);
        image.save("result.png");
    }
    delete rbResult;
};
QRhiResourceUpdateBatch *u = nextResourceUpdateBatch();
QRhiReadbackDescription rb; // no texture -> uses the current backbuffer of sc
u->readBackTexture(rb, rbResult);
cb->endPass(u);
rhi->endFrame(swapchain);

1回のリードバック操作では、1つのレイヤーの1ミップレベル（キューブマップの面、3Dスライス、またはテクスチャ配列の要素）が一度にコピーされます。レベルとレイヤーは、rb のそれぞれのフィールドで指定されます。

readBackBuffer() およびQRhi::resourceLimit()も参照してください 。

void QRhiResourceUpdateBatch::release()

バッチをプールに戻します。これは、バッチがQRhiCommandBuffer::beginPass()、QRhiCommandBuffer::endPass()、またはQRhiCommandBuffer::resourceUpdate() のいずれにも渡されていない場合にのみ使用してください。これらの関数は暗黙的に destroy() を呼び出すためです。

void QRhiResourceUpdateBatch::updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)

タイプQRhiBuffer::Dynamic で作成されたQRhiBuffer buf の領域を更新する処理をキューに入れます。

対象となる領域は、offset およびsize で指定されます。実際に書き込むバイトはdata で指定されますが、この領域には少なくともsize バイトの空き容量が必要です。

data はコピーされたものであり、この関数が返った後は安全に破棄または変更できます。

[since 6.10] void QRhiResourceUpdateBatch::updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, QByteArray data)

このオーバーロードでは、型QRhiBuffer::Dynamic で作成されたQRhiBuffer buf の領域を更新する処理をキューに追加します。 の領域は、コピーされるのではなく、バッチ内に移動されます。

data このオーバーロードでは、コピーされる代わりにバッチ内に移動されます。

この関数は Qt 6.10 で導入されました。

void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)

タイプQRhiBuffer::Immutable またはQRhiBuffer::Static で作成されたQRhiBuffer buf の領域を更新する処理をキューに追加します。

対象となる領域は、offset およびsize で指定されます。実際に書き込むバイトは、data で指定されますが、この領域には少なくともsize バイトの空き容量が必要です。

data はコピーされるため、この関数が返った後は安全に破棄または変更することができます。

[since 6.10] void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, QByteArray data)

型QRhiBuffer::Immutable またはQRhiBuffer::Static で作成されたQRhiBuffer buf 全体を更新する処理をキューに追加します。 は、このオーバーロードではコピーされるのではなく、バッチ内に移動されます。

data このオーバーロードでは、コピーされるのではなく、バッチ内に移動されます。

data size はbuf のサイズと等しくなければなりません。

この関数は Qt 6.10 で導入されました。

void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, const void *data)

タイプQRhiBuffer::Immutable またはQRhiBuffer::Static で作成されたQRhiBuffer buf 全体の更新をキューに追加します。

[since 6.10] void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, QByteArray data)

このオーバーロードでは、型QRhiBuffer::Immutable またはQRhiBuffer::Static で作成されたQRhiBuffer buf の領域を更新する処理を、コピーするのではなく、バッチに追加します。

data このオーバーロードでは、コピーされる代わりに、データがバッチ内に移動されます。

この関数は Qt 6.10 で導入されました。

void QRhiResourceUpdateBatch::uploadTexture(QRhiTexture *tex, const QImage &image)

テクスチャ `tex` のレイヤー 0 のミップレベル 0 に対応する画像データのアップロードをキューに登録します。

tex 非圧縮形式である必要があります。また、その形式はimage のQImage::format() と互換性がある必要があります。ソースデータはimage に記載されています。

void QRhiResourceUpdateBatch::uploadTexture(QRhiTexture *tex, const QRhiTextureUploadDescription &desc)

テクスチャtex の 1 つ以上のレイヤーに含まれる 1 つ以上のミップレベルについて、画像データのアップロードをキューに登録します。

コピーの詳細（ソースであるQImage または圧縮されたテクスチャデータ、領域、ターゲットレイヤーおよびレベル）については、desc に記載されています。