QRhiTextureSubresourceUploadDescription Class
描述了纹理上传操作中某一层中一个MIP级别的来源。更多内容...
| 标题： | #include <rhi/qrhi.h> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS GuiPrivate) target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake： | QT += gui-private |
| 自： | Qt 6.6 |
公共函数
| 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 |
详细说明
源内容可指定为QImage ，也可指定为原始blob。前者仅适用于格式可映射到QImage 的未压缩纹理，而后者支持所有格式，包括浮点格式和压缩格式。
destinationTopLeft() 指定目标矩形的左上角坐标。默认值为 (0, 0)。
空的sourceSize()（默认值）表示该大小被视为子资源的大小。对于基于QImage 的上传，这意味着源image() 的大小必须与子资源一致。如果提供原始数据，则必须在data() 中提供足够数量的字节。
sourceTopLeft() 仅支持基于QImage 的上传，并指定源矩形的左上角。
注意： 根据格式和后端的不同，设置 sourceSize() 或sourceTopLeft() 可能会在内部触发QImage 复制。
当提供原始数据且未通过setDataStride() 指定步长时，所提供数据的步长（行间距，即行长度以字节为单位）必须等于width * pixelSize ，其中pixelSize 表示单个像素占用的字节数，且行与行之间不得有额外填充。行起始位置无需对齐。
当输入原始数据中每行末尾存在未使用数据时，请将每行的总字节数作为参数调用setDataStride()。步长必须始终是单个像素所占字节数的倍数。行步长仅适用于未压缩格式的纹理图像数据。
注意： 源数据的格式 必须与纹理格式兼容。在许多图形 API 中，数据会原样复制到暂存缓冲区，QRhi 不会提供中间格式转换。这同样适用于浮点格式，例如，RGBA16F 要求源数据中包含半精度浮点数。
注意： 仅当QRhi::ImageDataStride 的返回值为supported 时，通过setDataStride()设置 步长才有效。实际上，除OpenGL ES 2.0外，其他环境均应支持此功能。
注意：当 指定了QImage 时 ，系统会自动考虑QImage::bytesPerLine() 返回的步长。
警告：当 指定了QImage ，且QImage 不拥有底层像素数据时 ，调用方必须确保相关数据在帧结束前保持有效。 （仅提交资源更新批次是不够的，数据必须保持有效直至调用QRhi::endFrame()，才能确保在所有后端之间具有可移植性）如果无法确保这一点，强烈建议调用方在将图像传递给 uploadTexture() 之前，先调用 QImage::detach() 解绑该图像。
注意：这是一个 兼容性保证有限的 RHI API，详情请参见QRhi 。
另请参阅 QRhiTextureUploadDescription 。
成员函数文档
[noexcept default] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()
构建一个空的子资源描述。
注意：一个 空的 QRhiTextureSubresourceUploadDescription 本身并无实际用途，不应提交至QRhiTextureUploadEntry 。至少应先设置图像或数据。
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QByteArray &data)
根据data 中指定的图像数据构建MIP级别描述。这同样适用于浮点格式和压缩格式。
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QImage &image)
使用image 构建MIP级别描述。
该size （image ）的大小必须与Mip级的大小相匹配。对于第0级，其大小即为texture size 。
image 的位深度必须与texture format 兼容。
要描述部分上传，请在后续调用setSourceSize()、setSourceTopLeft() 或setDestinationTopLeft()。
QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)
根据data 和size 中指定的图像数据，构建一个MIP级别描述。这同样适用于浮点数和压缩格式。
data 该函数返回后，可安全地销毁或修改该对象。
QByteArray QRhiTextureSubresourceUploadDescription::data() const
返回当前设置的原始像素数据。
另请参阅 setData()。
quint32 QRhiTextureSubresourceUploadDescription::dataStride() const
返回当前设置的数据步长。
另请参阅 setDataStride()。
QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft() const
返回当前设置的目标左上角位置。默认值为 (0, 0)。
另请参阅 setDestinationTopLeft()。
QImage QRhiTextureSubresourceUploadDescription::image() const
返回当前设置的QImage 。
另请参阅 setImage()。
void QRhiTextureSubresourceUploadDescription::setData(const QByteArray &data)
设置data 。
另请参阅 data()。
void QRhiTextureSubresourceUploadDescription::setDataStride(quint32 stride)
设置数据stride 的字节单位。默认值为0，且并非总是相关。 当提供原始图像数据data() 且未通过 setDataStride() 指定步长时，所提供数据的步长（行间距，即行长度，单位为字节）必须等于width * pixelSize ，其中pixelSize 表示单个像素占用的字节数，且行与行之间不得有额外填充。 否则，如果行与行之间存在额外空间，请设置一个非零的stride 。所有这些仅在提供原始图像数据时适用，而QImage 则无需如此，因为它拥有自己的stride 值。
注意：当 设置非零的stride 时 ，请确保数据中也包含最后一行的尾部填充，即总计至少有stride * height 字节。 虽然提供不包含最后一行填充的数据（即视 stride 为不适用于最后一行）可能是安全的，而且在 Vulkan 中确实是安全的， OpenGL 以及 D3D12 中确实是安全的，但这无法保证适用于所有后端，因此安全的方法是避免这种情况，并将最后一行与其他行一样处理。
注意： 仅当 `QRhi::ImageDataStride ` 返回值为 `supported` 时，通过 `setDataStride()`设置 步长才有效。
注意：当 指定了QImage 时，系统会自动考虑QImage::bytesPerLine()返回的步长，因此无需手动设置数据步长。
另请参阅 dataStride()。
void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)
设置目标区域的左上角位置p 。
注意：在 最常见的情况中 ，当图像数据源自QImage 时，如果目标位置加上源大小超过了目标纹理子资源的大小（即给定mip级别的大小），Qt会对无效的纹理上传大小进行裁剪。 在此情况下，调试输出中还会显示一条qWarning()消息。此举旨在避免当底层3D API发生崩溃，并在后续提交命令时导致GPU设备被移除时造成混淆。 无论如何，建议开发者始终在启用 Vulkan、D3D12 或 Metal 验证/调试层的情况下运行应用程序以进行验证，因为这些层对 API 使用情况提供了更广泛的检查。
另请参阅 destinationTopLeft()。
void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image)
设置image 。在加载纹理时，图像数据将按原样读取，不进行任何格式转换。
另请参阅 image()。
void QRhiTextureSubresourceUploadDescription::setSourceSize(const QSize &size)
将源地址size 的单位设置为像素。
注意： 根据格式和后端的不同，设置 sourceSize() 或sourceTopLeft() 可能会在内部触发QImage 操作。
另请参阅 sourceSize()。
void QRhiTextureSubresourceUploadDescription::setSourceTopLeft(const QPoint &p)
设置源图像的左上角位置p 。
注意： 根据格式和后端的不同，设置 sourceSize() 或sourceTopLeft() 可能会在内部触发QImage 操作。
另请参阅 sourceTopLeft()。
QSize QRhiTextureSubresourceUploadDescription::sourceSize() const
返回源大小（以像素为单位）。默认返回通过默认构造函数创建的QSize ，该对象表示整个子资源。
另请参阅 setSourceSize()。
QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft() const
返回当前设置的源图像左上角位置。默认值为 (0, 0)。
另请参阅 setSourceTopLeft()。
© 2026 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.
