QRhiTexture Class

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512));
if (!texture->create()) { error(); }
QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
QImage image(512, 512, QImage::Format_RGBA8888);
image.fill(Qt::green);
batch->uploadTexture(texture, image);
// ...
commandBuffer->resourceUpdate(batch); // or, alternatively, pass 'batch' to a beginPass() call

// determine newSize, e.g. based on the swapchain's output size or other factors
if (texture->pixelSize() != newSize) {
    texture->setPixelSize(newSize);
    if (!texture->create()) { error(); }
}
// continue using texture, fill it with new data

成员函数文档

int QRhiTexture::arrayRangeLength() const

返回调用setArrayRange()时暴露的数组范围大小。

另请参阅 setArrayRange()。

int QRhiTexture::arrayRangeStart() const

返回调用setArrayRange() 时生成的第一个数组层。

另请参阅 setArrayRange()。

int QRhiTexture::arraySize() const

返回纹理数组的大小。

另请参阅 setArraySize()。

[pure virtual] bool QRhiTexture::create()

创建相应的本机图形资源。如果由于之前调用了create()但未调用相应的destroy()，导致已存在相关资源，则会先隐式调用destroy()。

成功时返回true ，图形操作失败时返回false 。无论返回值如何，调用destroy()始终是安全的。

[virtual] bool QRhiTexture::createFrom(QRhiTexture::NativeTexture src)

与create() 类似，不同之处在于不会创建新的本机纹理。取而代之的是，将使用由src 指定的本机纹理资源。

这允许从外部图形引擎导入现有的原生纹理对象（该对象必须属于同一设备或共享上下文，具体取决于图形 API）。

如果指定的现有原生纹理对象已成功被封装为非拥有型的QRhiTexture ，则返回 true。

该操作的反向操作——即将由QRhiTexture 创建的原生纹理对象暴露给外部引擎——可通过nativeTexture() 实现。

int QRhiTexture::depth() const

返回 3D 纹理的深度。

另请参阅 setDepth()。

QRhiTexture::Flags QRhiTexture::flags() const

返回纹理标志。

另请参阅 setFlags()。

QRhiTexture::Format QRhiTexture::format() const

返回纹理格式。

另请参阅 setFormat()。

[virtual] QRhiTexture::NativeTexture QRhiTexture::nativeTexture()

返回该纹理的底层本机资源。如果后端不支持暴露底层本机资源，则返回值为空。

另请参阅 createFrom()。

QSize QRhiTexture::pixelSize() const

返回以像素为单位的尺寸。

另请参阅 setPixelSize()。

[since 6.8] QRhiTexture::ViewFormat QRhiTexture::readViewFormat() const

返回采样纹理时使用的视图格式。若未调用该函数，则默认视图格式与format() 相同。

该函数在 Qt 6.8 中引入。

另请参阅 setReadViewFormat()。

[override virtual] QRhiResource::Type QRhiTexture::resourceType() const

重写了：QRhiResource::resourceType() const。

返回资源类型。

int QRhiTexture::sampleCount() const

返回采样数。1 表示不进行多采样抗锯齿。

另请参阅 ` setSampleCount()`。

void QRhiTexture::setArrayRange(int startIndex, int count)

通常情况下，所有数组层都会被暴露出来，具体选择哪个层由着色器决定——在采样sampler2DArray 时，通过传递给texture() GLSL函数的第三个坐标来实现。当报告支持QRhi::TextureArrayRange 时，在调用create()或createFrom()之前先调用setArrayRange()，即可仅选择指定的范围，即从startIndex 开始的count 个元素。着色器逻辑可据此进行编写。

另请参阅 QRhi::TextureArrayRange 。

void QRhiTexture::setArraySize(int arraySize)

设置纹理arraySize 。

另请参阅 arraySize()。

void QRhiTexture::setDepth(int depth)

设置 3D 纹理的“depth ”。

另请参阅 depth()。

void QRhiTexture::setFlags(QRhiTexture::Flags f)

将纹理标志设置为f 。

另请参阅 flags()。

void QRhiTexture::setFormat(QRhiTexture::Format fmt)

将请求的纹理格式设置为fmt 。

另请参阅 format()。

[virtual] void QRhiTexture::setNativeLayout(int layout)

对于某些图形 API（例如 Vulkan），在集成直接使用该图形 API 的自定义渲染代码时，需要特别注意图像布局问题。此函数允许在执行原生渲染命令后，指定layout 中QRhiTexture 所对应的图像的预期布局。

例如，假设在由QRhiCommandBuffer::beginExternal() 和QRhiCommandBuffer::endExternal() 包围的代码块中，直接使用 Vulkan 将内容渲染到QRhiTexture 的 VkImage 中，随后在基于QRhi 的渲染通道中使用该图像进行纹理采样。为避免图像布局转换可能出现错误，可使用此函数指定当上述代码块中记录的命令完成后，图像布局将呈现何种状态。

仅在调用QRhiCommandBuffer::endExternal() 之后、后续的QRhiCommandBuffer::beginPass() 之前调用此函数才有意义。

在QRhi 后端中，若底层图形API未提供图像布局概念，则此函数无效。

void QRhiTexture::setPixelSize(const QSize &sz)

将纹理大小（以像素为单位）设置为sz 。

另请参阅 pixelSize()。

[since 6.8] void QRhiTexture::setReadViewFormat(const QRhiTexture::ViewFormat &fmt)

将着色器资源视图格式（或用于采样纹理的视图格式）设置为fmt 。默认情况下，会使用与纹理本身相同的格式（以及sRGB属性），因此在大多数情况下无需调用此函数。

只有当报告支持QRhi::TextureViewFormat 功能时，此设置才会生效。

该函数在 Qt 6.8 中引入。

另请参阅 readViewFormat()。

void QRhiTexture::setSampleCount(int s)

将采样次数设置为s 。

另请参阅 sampleCount()。

[since 6.8] void QRhiTexture::setWriteViewFormat(const QRhiTexture::ViewFormat &fmt)

将渲染目标视图格式设置为fmt 。默认情况下，会使用与纹理本身相同的格式（以及sRGB属性），因此在大多数情况下无需调用此函数。

提供写入视图格式的常见用例之一是处理外部提供的纹理：这些纹理在我们的控制范围之外，使用Vulkan或Direct 3D等3D API时采用了sRGB格式，但渲染引擎已在着色管道末端做好了处理线性化和转换为sRGB的准备。 在这种情况下，渲染到此类纹理时所需的是具有相同（但非 sRGB）格式的渲染目标视图（例如 VkImageView）。 （例如，如果从 OpenXR 实现中获取到 VK_FORMAT_R8G8B8A8_SRGB 纹理， 那么若渲染引擎的管道有此要求，渲染时很可能应使用 VK_FORMAT_R8G8B8A8_UNORM 视图；在此示例中，应调用该函数并传入一个格式为QRhiTexture::RGBA8 、且srgb 设置为false 的ViewFormat 对象）。

只有当报告支持QRhi::TextureViewFormat 功能时，才会考虑此设置。

该函数在 Qt 6.8 中引入。

另请参阅 writeViewFormat()。

[since 6.8] QRhiTexture::ViewFormat QRhiTexture::writeViewFormat() const

返回在向纹理写入数据以及在图像加载/存储操作中使用该纹理时所采用的视图格式。若未调用此函数，则默认视图格式与format() 中的设置相同。

该函数在 Qt 6.8 中引入。

另请参阅 setWriteViewFormat()。