QRhiResourceUpdateBatch Class

Dokumentation der Mitgliedsfunktionen

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

Stellt einen Textur-zu-Textur-Kopiervorgang von src nach dst in die Warteschlange, wie unter desc beschrieben.

void QRhiResourceUpdateBatch::generateMips(QRhiTexture *tex)

Stellt einen Vorgang zur Erzeugung von Mipmaps für die angegebene Textur „ tex “ in die Warteschlange ein.

2D- und Würfeltexturen werden unterstützt. 1D- und 3D-Texturen werden unterstützt, wenn die Funktion „ QRhi::OneDimensionalTextureMipmaps “ bzw. „ QRhi::ThreeDimensionalTextureMipmaps “ als unterstützt gemeldet wird.

bool QRhiResourceUpdateBatch::hasOptimalCapacity() const

Gibt „true“ zurück, bis die Anzahl der in diesem Batch in die Warteschlange gestellten Puffer- und Texturoperationen unter einen angemessenen Grenzwert fällt.

Der Rückgabewert ist „false“, wenn die Anzahl der diesem Batch hinzugefügten Puffer- und/oder Texturoperationen eine bestimmte Grenze erreicht hat oder kurz davor steht, diese zu erreichen. Der Batch ist auch danach voll funktionsfähig, muss jedoch möglicherweise zusätzlichen Speicher zuweisen. Daher sollte ein Renderer, der bei der Vorbereitung eines Frames viele Puffer- und Textur-Updates in einem einzigen Batch sammelt, die Funktionen „ submitting the batch “ und „ starting a new one “ in Betracht ziehen, wenn diese Funktion „false“ zurückgibt.

void QRhiResourceUpdateBatch::merge(QRhiResourceUpdateBatch *other)

Kopiert alle in der Warteschlange befindlichen Vorgänge aus dem „ other “-Batch in diesen.

Dies ermöglicht ein praktisches Muster, bei dem Ressourcenaktualisierungen, die bereits während des Initialisierungsschritts bekannt sind, in einem Batch gesammelt werden, der später beim Start des ersten Renderdurchgangs in einen anderen Batch zusammengeführt wird:

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)

Stellt das Zurücklesen eines Bereichs aus „ QRhiBuffer “ buf “ in die Warteschlange. Die Größe des Bereichs wird durch „ size “ in Byte angegeben, „ offset “ ist der Offset in Byte, ab dem mit dem Lesen begonnen werden soll.

Ein Rücklesen erfolgt asynchron. result enthält einen Callback, der aufgerufen wird, sobald der Vorgang abgeschlossen ist. Die Daten werden in QRhiReadbackResult::data bereitgestellt. Bei erfolgreichem Abschluss hat QByteArray eine Größe, die size entspricht. Bei einem Fehler ist QByteArray leer.

Siehe auch readBackTexture(), QRhi::isFeatureSupported() und QRhi::resourceLimit().

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

Stellt einen Kopiervorgang von einer Textur auf den Host in die Warteschlange, wie unter rb beschrieben.

Normalerweise gibt rb einen „ QRhiTexture “ als Quelle an. Wenn die Swapchain im aktuellen Frame jedoch mit QRhiSwapChain::UsedAsTransferSource erstellt wurde, kann sie auch als Quelle für das Zurücklesen dienen. Lassen Sie dazu die Textur in rb auf „null“ gesetzt.

Im Gegensatz zu anderen Operationen müssen die Ergebnisse hier von der Anwendung verarbeitet werden. Daher liefert ` result ` nicht nur die Daten, sondern auch einen Callback, da Operationen auf dem Batch von Natur aus asynchron sind:

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

Ein einzelner Readback-Vorgang kopiert jeweils eine Mip-Ebene einer Schicht (Cubemap-Fläche, 3D-Schnitt oder Textur-Array-Element). Die Ebene und die Schicht werden durch die entsprechenden Felder in rb angegeben.

Siehe auch readBackBuffer() und QRhi::resourceLimit().

void QRhiResourceUpdateBatch::release()

Gibt den Batch an den Pool zurück. Dies sollte nur verwendet werden, wenn der Batch nicht an eine der Methoden QRhiCommandBuffer::beginPass(), QRhiCommandBuffer::endPass() oder QRhiCommandBuffer::resourceUpdate() übergeben wird, da diese implizit destroy() aufrufen.

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

Stellt die Aktualisierung eines Bereichs eines QRhiBuffer buf in die Warteschlange, der mit dem Typ QRhiBuffer::Dynamic erstellt wurde.

Der Bereich wird durch offset und size angegeben. Die tatsächlich zu schreibenden Bytes werden durch data angegeben, das mindestens size Bytes zur Verfügung haben muss.

data wird kopiert und kann nach der Rückkehr dieser Funktion sicher zerstört oder geändert werden.

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

Stellt die Aktualisierung eines Bereichs eines „ QRhiBuffer “ buf in die Warteschlange, der mit dem Typ „ QRhiBuffer::Dynamic “ erstellt wurde.

data wird bei dieser Überladung in den Batch verschoben, anstatt kopiert zu werden.

Diese Funktion wurde in Qt 6.10 eingeführt.

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

Stellt die Aktualisierung eines Bereichs eines QRhiBuffer buf in die Warteschlange, der mit dem Typ QRhiBuffer::Immutable oder QRhiBuffer::Static erstellt wurde.

Der Bereich wird durch offset und size angegeben. Die tatsächlich zu schreibenden Bytes werden durch data angegeben, das mindestens size Bytes zur Verfügung haben muss.

data wird kopiert und kann nach der Rückkehr dieser Funktion bedenkenlos gelöscht oder geändert werden.

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

Stellt die Aktualisierung des gesamten „ QRhiBuffer “ ( buf ) in die Warteschlange, der mit dem Typ „ QRhiBuffer::Immutable “ oder „ QRhiBuffer::Static “ erstellt wurde.

data wird bei dieser Überladung in den Batch verschoben, anstatt kopiert zu werden.

data `size` muss der Größe von ` buf` entsprechen.

Diese Funktion wurde in Qt 6.10 eingeführt.

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

Stellt die Aktualisierung der gesamten „ QRhiBuffer “ ( buf ) in die Warteschlange, die mit dem Typ „ QRhiBuffer::Immutable “ oder „ QRhiBuffer::Static “ erstellt wurde.

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

Stellt die Aktualisierung eines Bereichs eines ` QRhiBuffer ` buf in die Warteschlange, der mit dem Typ ` QRhiBuffer::Immutable ` oder ` QRhiBuffer::Static` erstellt wurde.

data wird bei dieser Überladung in den Batch verschoben, anstatt kopiert zu werden.

Diese Funktion wurde in Qt 6.10 eingeführt.

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

Stellt das Hochladen der Bilddaten für Mip-Ebene 0 von Ebene 0 der Textur tex in die Warteschlange.

tex muss ein unkomprimiertes Format haben. Das Format muss außerdem mit der Funktion ` QImage::format()` von ` image` kompatibel sein. Die Quelldaten sind in ` image` angegeben.

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

Stellt das Hochladen der Bilddaten für eine oder mehrere Mip-Stufen in einer oder mehreren Ebenen der Textur tex in die Warteschlange.

Die Details des Kopiervorgangs (Quell QImage oder komprimierte Texturdaten, Bereiche, Zielebenen und -stufen) werden unter desc beschrieben.