QRhiTextureUploadDescription Class

Detaillierte Beschreibung

Wird mit QRhiResourceUpdateBatch::uploadTexture() verwendet. Diese Funktion hat zwei Varianten: eine mit einem QImage und eine mit einer QRhiTextureUploadDescription. Erstere ist eine Komfortversion, die intern eine QRhiTextureUploadDescription mit einem einzelnen Bild auf Ebene 0 für Layer 0 erstellt.

Ein Beispiel für den häufigen, einfachen Fall, dass man den Inhalt einer QImage auf eine QRhiTexture mit einer passenden Pixelgröße hochladen möchte:

QImage image(256, 256, QImage::Format_RGBA8888);
image.fill(Qt::green); // or could use a QPainter targeting image
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256));
texture->create();
QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
u->uploadTexture(texture, image);

Wenn Cubemaps, vorgenerierte mip-Bilder, komprimierte Texturen oder Teil-Uploads involviert sind, müssen Anwendungen stattdessen diese Klasse verwenden.

QRhiTextureUploadDescription ermöglicht auch die Angabe von gebündelten Uploads, die z. B. bei der Erzeugung einer Atlas- oder Glyphen-Cache-Textur nützlich sind: Mehrere partielle Uploads für dieselbe Subresource (d. h. dieselbe Ebene und denselben Layer) werden unterstützt und können, abhängig vom Backend und der zugrunde liegenden Grafik-API, effizienter sein, wenn sie in derselben QRhiTextureUploadDescription gebündelt werden, als wenn für jede einzelne Textur einzelne uploadTexture()-Befehle ausgegeben werden.

Die Angabe der Flächen einer Cubemap könnte zum Beispiel wie folgt aussehen:

QImage faces[6];
// ...
QVarLengthArray<QRhiTextureUploadEntry, 6> entries;
for (int i = 0; i < 6; ++i)
  entries.append(QRhiTextureUploadEntry(i, 0, faces[i]));
QRhiTextureUploadDescription desc;
desc.setEntries(entries.cbegin(), entries.cend());
resourceUpdates->uploadTexture(texture, desc);

Ein weiteres Beispiel, das mip-Bilder für eine komprimierte Textur angibt:

QList<QRhiTextureUploadEntry> entries;
const int mipCount = rhi->mipLevelsForSize(compressedTexture->pixelSize());
for (int level = 0; level < mipCount; ++level) {
    const QByteArray compressedDataForLevel = ..
    entries.append(QRhiTextureUploadEntry(0, level, compressedDataForLevel));
}
QRhiTextureUploadDescription desc;
desc.setEntries(entries.cbegin(), entries.cend());
resourceUpdates->uploadTexture(compressedTexture, desc);

Bei teilweisen Uploads, die auf dieselbe Subressource abzielen, wird empfohlen, sie nach Möglichkeit in einer einzigen Upload-Anforderung zusammenzufassen:

QRhiTextureSubresourceUploadDescription subresDesc(image);
subresDesc.setSourceSize(QSize(10, 10));
subResDesc.setDestinationTopLeft(QPoint(50, 40));
QRhiTextureUploadEntry entry(0, 0, subresDesc); // layer 0, level 0

QRhiTextureSubresourceUploadDescription subresDesc2(image);
subresDesc2.setSourceSize(QSize(30, 40));
subResDesc2.setDestinationTopLeft(QPoint(100, 200));
QRhiTextureUploadEntry entry2(0, 0, subresDesc2); // layer 0, level 0, i.e. same subresource

QRhiTextureUploadDescription desc({ entry, entry2});
resourceUpdates->uploadTexture(texture, desc);