QRhiTextureUploadDescription Class Reference

\inmodule QtGui More...

#include <qrhi.h>

Collaboration diagram for QRhiTextureUploadDescription:

Public Member Functions
	QRhiTextureUploadDescription ()=default
	Constructs an empty texture upload description.
	QRhiTextureUploadDescription (const QRhiTextureUploadEntry &entry)
	Constructs a texture upload description with a single subresource upload described by entry.
	QRhiTextureUploadDescription (std::initializer_list< QRhiTextureUploadEntry > list)
	Constructs a texture upload description with the specified list of entries.
void	setEntries (std::initializer_list< QRhiTextureUploadEntry > list)
	Sets the list of entries.
template<typename InputIterator >
void	setEntries (InputIterator first, InputIterator last)
	Sets the list of entries using the iterators first and last.
const QRhiTextureUploadEntry *	cbeginEntries () const
const QRhiTextureUploadEntry *	cendEntries () const
const QRhiTextureUploadEntry *	entryAt (qsizetype index) const
qsizetype	entryCount () const

Detailed Description

\inmodule QtGui

Since

6.6

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.

An example of the the common, simple case of wanting to upload the contents of a QImage to a QRhiTexture with a matching pixel size:

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

When cubemaps, pre-generated mip images, compressed textures, or partial uploads are involved, applications will have to use 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 \l{QRhiResourceUpdateBatch::uploadTexture()}{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];
// ...
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);

Another example that specifies mip images for a compressed texture:

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

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

Note

This is a RHI API with limited compatibility guarantees, see \l QRhi for details.

See also

QRhiResourceUpdateBatch

Definition at line 703 of file qrhi.h.

Constructor & Destructor Documentation

QRhiTextureUploadDescription() [1/3]

QRhiTextureUploadDescription::QRhiTextureUploadDescription ( )

default

Constructs an empty texture upload description.

QRhiTextureUploadDescription() [2/3]

QRhiTextureUploadDescription::QRhiTextureUploadDescription

(

const QRhiTextureUploadEntry &

entry

)

Constructs a texture upload description with a single subresource upload described by entry.

Definition at line 2989 of file qrhi.cpp.

References QVarLengthArray< T, Prealloc >::append().

Here is the call graph for this function:

QRhiTextureUploadDescription() [3/3]

QRhiTextureUploadDescription::QRhiTextureUploadDescription

(

std::initializer_list< QRhiTextureUploadEntry >

list

)

Constructs a texture upload description with the specified list of entries.

Note

list can also contain multiple QRhiTextureUploadEntry elements with the same layer and level. This makes sense when those uploads are partial, meaning their subresource description has a source size or image smaller than the subresource dimensions, and can be more efficient than issuing separate uploadTexture()'s.

Definition at line 3003 of file qrhi.cpp.

Member Function Documentation

cbeginEntries()

const QRhiTextureUploadEntry * QRhiTextureUploadDescription::cbeginEntries ( ) const

inline

Returns

a const iterator pointing to the first item in the entry list.

Definition at line 717 of file qrhi.h.

cendEntries()

const QRhiTextureUploadEntry * QRhiTextureUploadDescription::cendEntries ( ) const

inline

Returns

a const iterator pointing just after the last item in the entry list.

Definition at line 718 of file qrhi.h.

entryAt()

const QRhiTextureUploadEntry * QRhiTextureUploadDescription::entryAt ( qsizetype  index ) const

inline

Returns

the entry at index.

Definition at line 719 of file qrhi.h.

entryCount()

qsizetype QRhiTextureUploadDescription::entryCount ( ) const

inline

Returns

the number of entries.

Definition at line 720 of file qrhi.h.

setEntries() [1/2]

template<typename InputIterator >

template< typename InputIterator > void QRhiTextureUploadDescription::setEntries ( InputIterator  first, InputIterator  last  )

inline

Sets the list of entries using the iterators first and last.

Definition at line 712 of file qrhi.h.

setEntries() [2/2]

void QRhiTextureUploadDescription::setEntries ( std::initializer_list< QRhiTextureUploadEntry >  list )

inline

Sets the list of entries.

Definition at line 710 of file qrhi.h.

References list.

---

The documentation for this class was generated from the following files:

• qtbase/src/gui/rhi/qrhi.h
• qtbase/src/gui/rhi/qrhi.cpp