QRhiTextureUploadDescription Class

Description détaillée

Utilisée avec ` QRhiResourceUpdateBatch::uploadTexture()`. Cette fonction dispose de deux variantes : l’une prenant un ` QImage ` et l’autre un `QRhiTextureUploadDescription`. La première est une version simplifiée qui crée en interne un `QRhiTextureUploadDescription` avec une seule image ciblant le niveau 0 pour le calque 0.

Voici un exemple de cas courant et simple où l'on souhaite télécharger le contenu d'un objet ` QImage ` vers un objet ` QRhiTexture ` avec une taille de pixel correspondante :

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

Lorsque des cubemaps, des images mip pré-générées, des textures compressées ou des téléchargements partiels sont impliqués, les applications devront utiliser cette classe à la place.

QRhiTextureUploadDescription permet également de spécifier des chargements par lots, ce qui est utile par exemple lors de la génération d’un atlas ou d’une texture de cache de glyphes : les chargements multiples et partiels pour une même sous-ressource (c'est-à-dire le même calque et le même niveau) sont pris en charge et peuvent, selon le backend et l'API graphique sous-jacente, s'avérer plus efficaces lorsqu'ils sont regroupés dans la même instance de `QRhiTextureUploadDescription` plutôt que d'émettre des commandes ` uploadTexture()` individuelles pour chacun d'entre eux.

Par exemple, la spécification des faces d’une cubemap pourrait ressembler à ceci :

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

Autre exemple spécifiant des images mip pour une texture compressée :

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

En cas de chargements partiels ciblant la même sous-ressource, il est recommandé de les regrouper en une seule requête de chargement, dans la mesure du possible :

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