Back to Doc.qt.io
Contact Us Blog Download Qt

QRhiTextureSubresourceUploadDescription Class

Describes the source for one mip level in a layer in a texture upload operation. More...

Header: #include <rhi/qrhi.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)
qmake: QT += gui-private
Since: Qt 6.6

Public Functions

QRhiTextureSubresourceUploadDescription()
QRhiTextureSubresourceUploadDescription(const QByteArray &data)
QRhiTextureSubresourceUploadDescription(const QImage &image)
QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)
QByteArray data() const
quint32 dataStride() const
QPoint destinationTopLeft() const
QImage image() const
void setData(const QByteArray &data)
void setDataStride(quint32 stride)
void setDestinationTopLeft(const QPoint &p)
void setImage(const QImage &image)
void setSourceSize(const QSize &size)
void setSourceTopLeft(const QPoint &p)
QSize sourceSize() const
QPoint sourceTopLeft() const

Detailed Description

The source content is specified either as a QImage or as a raw blob. The former is only allowed for uncompressed textures with a format that can be mapped to QImage, while the latter is supported for all formats, including floating point and compressed.

Note: image() and data() cannot be both set at the same time.

destinationTopLeft() specifies the top-left corner of the target rectangle. Defaults to (0, 0).

An empty sourceSize() (the default) indicates that size is assumed to be the size of the subresource. With QImage-based uploads this implies that the size of the source image() must match the subresource. When providing raw data instead, sufficient number of bytes must be provided in data().

sourceTopLeft() is supported only for QImage-based uploads, and specifies the top-left corner of the source rectangle.

Note: Setting sourceSize() or sourceTopLeft() may trigger a QImage copy internally, depending on the format and the backend.

When providing raw data, and the stride is not specified via setDataStride(), the stride (row pitch, row length in bytes) of the provided data must be equal to width * pixelSize where pixelSize is the number of bytes used for one pixel, and there must be no additional padding between rows. There is no row start alignment requirement.

When there is unused data at the end of each row in the input raw data, call setDataStride() with the total number of bytes per row. The stride must always be a multiple of the number of bytes for one pixel. The row stride is only applicable to image data for textures with an uncompressed format.

Note: The format of the source data must be compatible with the texture format. With many graphics APIs the data is copied as-is into a staging buffer, there is no intermediate format conversion provided by QRhi. This applies to floating point formats as well, with, for example, RGBA16F requiring half floats in the source data.

Note: Setting the stride via setDataStride() is only functional when QRhi::ImageDataStride is reported as supported. In practice this can be expected to be supported everywhere except for OpenGL ES 2.0.

Note: When a QImage is given, the stride returned from QImage::bytesPerLine() is taken into account automatically.

Warning: When a QImage is given and the QImage does not own the underlying pixel data, it is up to the caller to ensure that the associated data stays valid until the end of the frame. (just submitting the resource update batch is not sufficient, the data must stay valid until QRhi::endFrame() is called in order to be portable across all backends) If this cannot be ensured, the caller is strongly encouraged to call QImage::detach() on the image before passing it to uploadTexture().

Note: This is a RHI API with limited compatibility guarantees, see QRhi for details.

See also QRhiTextureUploadDescription.

Member Function Documentation

[noexcept] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()

Constructs an empty subresource description.

Note: an empty QRhiTextureSubresourceUploadDescription is not useful on its own and should not be submitted to a QRhiTextureUploadEntry. At minimum image or data must be set first.

[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QByteArray &data)

Constructs a mip level description with the image data specified by data. This is suitable for floating point and compressed formats as well.

[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QImage &image)

Constructs a mip level description with a image.

The size of image must match the size of the mip level. For level 0 that is the texture size.

The bit depth of image must be compatible with the texture format.

To describe a partial upload, call setSourceSize(), setSourceTopLeft(), or setDestinationTopLeft() afterwards.

QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)

Constructs a mip level description with the image data is specified by data and size. This is suitable for floating point and compressed formats as well.

data can safely be destroyed or changed once this function returns.

QByteArray QRhiTextureSubresourceUploadDescription::data() const

Returns the currently set raw pixel data.

See also setData().

quint32 QRhiTextureSubresourceUploadDescription::dataStride() const

Returns the currently set data stride.

See also setDataStride().

QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft() const

Returns the currently set destination top-left position. Defaults to (0, 0).

See also setDestinationTopLeft().

QImage QRhiTextureSubresourceUploadDescription::image() const

Returns the currently set QImage.

See also setImage().

void QRhiTextureSubresourceUploadDescription::setData(const QByteArray &data)

Sets data.

Note: image() and data() cannot be both set at the same time.

See also data().

void QRhiTextureSubresourceUploadDescription::setDataStride(quint32 stride)

Sets the data stride in bytes. By default this is 0 and not always relevant. When providing raw data(), and the stride is not specified via setDataStride(), the stride (row pitch, row length in bytes) of the provided data must be equal to width * pixelSize where pixelSize is the number of bytes used for one pixel, and there must be no additional padding between rows. Otherwise, if there is additional space between the lines, set a non-zero stride. All this is applicable only when raw image data is provided, and is not necessary when working QImage since that has its own stride value.

Note: Setting the stride via setDataStride() is only functional when QRhi::ImageDataStride is reported as supported.

Note: When a QImage is given, the stride returned from QImage::bytesPerLine() is taken into account automatically and therefore there is no need to set the data stride manually.

See also dataStride().

void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)

Sets the destination top-left position p.

See also destinationTopLeft().

void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image)

Sets image. Upon textures loading, the image data will be read as is, with no formats conversions.

Note: image() and data() cannot be both set at the same time.

See also image().

void QRhiTextureSubresourceUploadDescription::setSourceSize(const QSize &size)

Sets the source size in pixels.

Note: Setting sourceSize() or sourceTopLeft() may trigger a QImage copy internally, depending on the format and the backend.

See also sourceSize().

void QRhiTextureSubresourceUploadDescription::setSourceTopLeft(const QPoint &p)

Sets the source top-left position p.

Note: Setting sourceSize() or sourceTopLeft() may trigger a QImage copy internally, depending on the format and the backend.

See also sourceTopLeft().

QSize QRhiTextureSubresourceUploadDescription::sourceSize() const

Returns the source size in pixels. Defaults to a default-constructed QSize, which indicates the entire subresource.

See also setSourceSize().

QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft() const

Returns the currently set source top-left position. Defaults to (0, 0).

See also setSourceTopLeft().

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.