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。

与此操作相反，可以通过nativeTexture() 将QRhiTexture 创建的本地纹理对象公开给外来引擎。

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() 常量。

返回资源类型。

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)

设置三维纹理的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 的自定义渲染代码时需要特别注意图像布局。该函数允许在执行本机渲染命令后，与支持QRhiTexture 的图像所处的预期layout 进行通信。

例如，考虑在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-ness），在大多数情况下无需调用此函数。

只有在报告支持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-ness），因此在大多数情况下无需调用此函数。

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

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

此函数在 Qt 6.8 中引入。

另请参阅 writeViewFormat()。

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

返回写入纹理和使用图像载入/存储时使用的视图格式。未调用时，视图格式假定与format() 相同。

此函数在 Qt 6.8 中引入。

另请参阅 setWriteViewFormat()。