QRhiTextureUploadDescription Class

Detailed Description

Describes a texture upload operation.

Used with QRhiResourceUpdateBatch::uploadTexture(). That function has two variants: one taking a QImage and one taking a QRhiTextureUploadDescription. The former is a convenience version, internally creating a QRhiTextureUploadDescription with a single image targeting level 0 for layer 0. However, when cubemaps, pre-generated mip images, or compressed textures are involved, applications will have to work directly with this class instead.

QRhiTextureUploadDescription also enables specifying batched uploads, which are useful for example when generating an atlas or glyph cache texture: multiple, partial uploads for the same subresource (meaning the same layer and level) are supported, and can be, depending on the backend and the underlying graphics API, more efficient when batched into the same QRhiTextureUploadDescription as opposed to issuing individual uploadTexture() commands for each of them.

Note: Cubemaps have one layer for each of the six faces in the order +X, -X, +Y, -Y, +Z, -Z.

For example, specifying the faces of a cubemap could look like the following:

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

Another example that specifies mip images for a compressed texture:

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

With partial uploads targeting the same subresource, it is recommended to batch them into a single upload request, whenever 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);