Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
QRhiTextureSubresourceUploadDescription Class Reference

\inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h More...

#include <qrhi.h>

Collaboration diagram for QRhiTextureSubresourceUploadDescription:

Public Member Functions

 QRhiTextureSubresourceUploadDescription ()=default
 Constructs an empty subresource description.
 QRhiTextureSubresourceUploadDescription (const QImage &image)
 Constructs a mip level description with a image.
 QRhiTextureSubresourceUploadDescription (const void *data, quint32 size)
 Constructs a mip level description with the image data is specified by data and size.
 QRhiTextureSubresourceUploadDescription (const QByteArray &data)
 Constructs a mip level description with the image data specified by data.
QImage image () const
void setImage (const QImage &image)
 Sets image.
QByteArray data () const
void setData (const QByteArray &data)
 Sets data.
quint32 dataStride () const
void setDataStride (quint32 stride)
 Sets the data stride in bytes.
QPoint destinationTopLeft () const
void setDestinationTopLeft (const QPoint &p)
 Sets the destination top-left position p.
QSize sourceSize () const
void setSourceSize (const QSize &size)
 Sets the source size in pixels.
QPoint sourceTopLeft () const
void setSourceTopLeft (const QPoint &p)
 Sets the source top-left position p.

Detailed Description

\inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h

Since
6.6

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

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.
Setting the stride via setDataStride() is only functional when QRhi::ImageDataStride is reported as \l{QRhi::isFeatureSupported()}{supported}. In practice this can be expected to be supported everywhere except for OpenGL ES 2.0.
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 \l QRhi for details.
See also
QRhiTextureUploadDescription

Definition at line 660 of file qrhi.h.

Constructor & Destructor Documentation

◆ QRhiTextureSubresourceUploadDescription() [1/4]

QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription ( )
default

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.

◆ QRhiTextureSubresourceUploadDescription() [2/4]

QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription ( const QImage & image)
explicit

Constructs a mip level description with a image.

The \l{QImage::size()}{size} of image must match the size of the mip level. For level 0 that is the \l{QRhiTexture::pixelSize()}{texture size}.

The bit depth of image must be compatible with the \l{QRhiTexture::Format}{texture format}.

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

Definition at line 2953 of file qrhi.cpp.

◆ QRhiTextureSubresourceUploadDescription() [3/4]

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.

Definition at line 2965 of file qrhi.cpp.

◆ QRhiTextureSubresourceUploadDescription() [4/4]

QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription ( const QByteArray & data)
explicit

Constructs a mip level description with the image data specified by data.

This is suitable for floating point and compressed formats as well.

Definition at line 2974 of file qrhi.cpp.

Member Function Documentation

◆ data()

QByteArray QRhiTextureSubresourceUploadDescription::data ( ) const
inline
Returns
the currently set raw pixel data.

Definition at line 671 of file qrhi.h.

◆ dataStride()

quint32 QRhiTextureSubresourceUploadDescription::dataStride ( ) const
inline
Returns
the currently set data stride.

Definition at line 674 of file qrhi.h.

◆ destinationTopLeft()

QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft ( ) const
inline
Returns
the currently set destination top-left position. Defaults to (0, 0).

Definition at line 677 of file qrhi.h.

◆ image()

QImage QRhiTextureSubresourceUploadDescription::image ( ) const
inline
Returns
the currently set QImage.

Definition at line 668 of file qrhi.h.

◆ setData()

void QRhiTextureSubresourceUploadDescription::setData ( const QByteArray & data)
inline

Sets data.

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

Definition at line 672 of file qrhi.h.

◆ setDataStride()

void QRhiTextureSubresourceUploadDescription::setDataStride ( quint32 stride)
inline

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 \l{QImage::bytesPerLine()}{stride} value.

Note
Setting the stride via setDataStride() is only functional when QRhi::ImageDataStride is reported as \l{QRhi::isFeatureSupported()}{supported}.
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.

Definition at line 675 of file qrhi.h.

◆ setDestinationTopLeft()

void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft ( const QPoint & p)
inline

Sets the destination top-left position p.

Note
In the most common case of sourcing the image data from a QImage, Qt performs clamping of invalid texture upload sizes when the destination position + the source size exceeds the size of the targeted texture subresource (i.e, the size at the given mip level). There is also a qWarning() message printed on the debug output in this case. This is done in order to avoid confusion when the underlying 3D APIs crash and lead to GPU device removals at a later point when submitting the commands. Regardless, developers are encouraged to always validate applications by running with the Vulkan, D3D12, or Metal validation/debug layers enabled, since those offer a much wider range of checks on API usage.

Definition at line 678 of file qrhi.h.

◆ setImage()

void QRhiTextureSubresourceUploadDescription::setImage ( const QImage & image)
inline

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.

Definition at line 669 of file qrhi.h.

◆ setSourceSize()

void QRhiTextureSubresourceUploadDescription::setSourceSize ( const QSize & size)
inline

Sets the source size in pixels.

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

Definition at line 681 of file qrhi.h.

◆ setSourceTopLeft()

void QRhiTextureSubresourceUploadDescription::setSourceTopLeft ( const QPoint & p)
inline

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.

Definition at line 684 of file qrhi.h.

◆ sourceSize()

QSize QRhiTextureSubresourceUploadDescription::sourceSize ( ) const
inline
Returns
the source size in pixels. Defaults to a default-constructed QSize, which indicates the entire subresource.

Definition at line 680 of file qrhi.h.

◆ sourceTopLeft()

QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft ( ) const
inline
Returns
the currently set source top-left position. Defaults to (0, 0).

Definition at line 683 of file qrhi.h.

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