QRhiTextureSubresourceUploadDescription Class
描述纹理上传操作中一个图层中一个 mip 层的来源。更多
| 头文件： | #include <rhi/qrhi.h> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Gui)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() 取得每行的总字节数。跨距必须始终是一个像素字节数的倍数。行跨距仅适用于未压缩格式的纹理图像数据。
注意： 源数据的格式必须与纹理格式兼容。对于许多图形应用程序接口，数据会被原样复制到暂存缓冲区中，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] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()
构造一个空的子资源描述。
注意： 空的 QRhiTextureSubresourceUploadDescription 本身并无用处，不应提交到QRhiTextureUploadEntry 。至少必须先设置图像或数据。
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QByteArray &data)
使用data 指定的图像数据构建 mip 级描述。这也适用于浮点格式和压缩格式。
[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QImage &image)
用image 构建 mip 级别描述。
image 的size 必须与 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 值。
注意： 通过 setDataStride() 设置跨距仅在QRhi::ImageDataStride 报告为supported 时有效。
注： 当给出QImage 时，将自动考虑从QImage::bytesPerLine() 返回的跨距，因此无需手动设置数据跨距。
另请参见 dataStride()。
void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)
设置目标左上角位置p 。
另请参阅 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()。
© 2025 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.
