QRhiTextureUploadDescription Class

Description détaillée

Utilisée avec QRhiResourceUpdateBatch::uploadTexture(). Cette fonction a deux variantes : l'une prenant un QImage et l'autre prenant un QRhiTextureUploadDescription. La première est une version de commodité, créant en interne un QRhiTextureUploadDescription avec une seule image ciblant le niveau 0 pour la couche 0.

Un exemple du cas simple et courant où l'on souhaite télécharger le contenu d'un site QImage vers un site 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 télé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 glyphe : plusieurs téléchargements partiels pour la même sous-ressource (c'est-à-dire la même couche et le même niveau) sont pris en charge et peuvent être, en fonction du backend et de l'API graphique sous-jacente, plus efficaces lorsqu'ils sont regroupés dans le même 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 peut ressembler à ce qui suit :

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

Un autre exemple qui spécifie 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);

Lorsque des téléchargements partiels ciblent la même sous-ressource, il est recommandé de les regrouper en une seule demande de télé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);