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

Member Function Documentation

int QRhiTexture::arrayRangeLength() const

Returns the exposed array range size when setArrayRange() was called.

See also setArrayRange().

int QRhiTexture::arrayRangeStart() const

Returns the first array layer when setArrayRange() was called.

See also setArrayRange().

int QRhiTexture::arraySize() const

Returns the texture array size.

See also setArraySize().

[pure virtual] bool QRhiTexture::create()

Creates the corresponding native graphics resources. If there are already resources present due to an earlier create() with no corresponding destroy(), then destroy() is called implicitly first.

Returns true when successful, false when a graphics operation failed. Regardless of the return value, calling destroy() is always safe.

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

Similar to create(), except that no new native textures are created. Instead, the native texture resources specified by src is used.

This allows importing an existing native texture object (which must belong to the same device or sharing context, depending on the graphics API) from an external graphics engine.

Returns true if the specified existing native texture object has been successfully wrapped as a non-owning QRhiTexture.

The opposite of this operation, exposing a QRhiTexture-created native texture object to a foreign engine, is possible via nativeTexture().

int QRhiTexture::depth() const

Returns the depth for 3D textures.

See also setDepth().

QRhiTexture::Flags QRhiTexture::flags() const

Returns the texture flags.

See also setFlags().

QRhiTexture::Format QRhiTexture::format() const

Returns the texture format.

See also setFormat().

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

Returns the underlying native resources for this texture. The returned value will be empty if exposing the underlying native resources is not supported by the backend.

See also createFrom().

QSize QRhiTexture::pixelSize() const

Returns the size in pixels.

See also setPixelSize().

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

Returns the view format used when sampling the texture. When not called, the view format is assumed to be the same as format().

This function was introduced in Qt 6.8.

See also setReadViewFormat().

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

Reimplements: QRhiResource::resourceType() const.

Returns the resource type.

int QRhiTexture::sampleCount() const

Returns the sample count. 1 means no multisample antialiasing.

See also setSampleCount().

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

Normally all array layers are exposed and it is up to the shader to select the layer via the third coordinate passed to the texture() GLSL function when sampling the sampler2DArray. When QRhi::TextureArrayRange is reported as supported, calling setArrayRange() before create() or createFrom() requests selecting only the specified range, count elements starting from startIndex. The shader logic can then be written with this in mind.

See also QRhi::TextureArrayRange.

void QRhiTexture::setArraySize(int arraySize)

Sets the texture arraySize.

See also arraySize().

void QRhiTexture::setDepth(int depth)

Sets the depth for a 3D texture.

See also depth().

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

Sets the texture flags to f.

See also flags().

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

Sets the requested texture format to fmt.

See also format().

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

With some graphics APIs, such as Vulkan, integrating custom rendering code that uses the graphics API directly needs special care when it comes to image layouts. This function allows communicating the expected layout the image backing the QRhiTexture is in after the native rendering commands.

For example, consider rendering into a QRhiTexture's VkImage directly with Vulkan in a code block enclosed by QRhiCommandBuffer::beginExternal() and QRhiCommandBuffer::endExternal(), followed by using the image for texture sampling in a QRhi-based render pass. To avoid potentially incorrect image layout transitions, this function can be used to indicate what the image layout will be once the commands recorded in said code block complete.

Calling this function makes sense only after QRhiCommandBuffer::endExternal() and before a subsequent QRhiCommandBuffer::beginPass().

This function has no effect with QRhi backends where the underlying graphics API does not expose a concept of image layouts.

void QRhiTexture::setPixelSize(const QSize &sz)

Sets the texture size, specified in pixels, to sz.

See also pixelSize().

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

Sets the shader resource view format (or the format of the view used for sampling the texture) to fmt. By default the same format (and sRGB-ness) is used as the texture itself, and in most cases this function does not need to be called.

This setting is only taken into account when the QRhi::TextureViewFormat feature is reported as supported.

This function was introduced in Qt 6.8.

See also readViewFormat().

void QRhiTexture::setSampleCount(int s)

Sets the sample count to s.

See also sampleCount().

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

Sets the render target view format to fmt. By default the same format (and sRGB-ness) is used as the texture itself, and in most cases this function does not need to be called.

One common use case for providing a write view format is working with externally provided textures that, outside of our control, use an sRGB format with 3D APIs such as Vulkan or Direct 3D, but the rendering engine is already prepared to handle linearization and conversion to sRGB at the end of its shading pipeline. In this case what is wanted when rendering into such a texture is a render target view (e.g. VkImageView) that has the same, but non-sRGB format. (if e.g. from an OpenXR implementation one gets a VK_FORMAT_R8G8B8A8_SRGB texture, it is likely that rendering into it should be done using a VK_FORMAT_R8G8B8A8_UNORM view, if that is what the rendering engine's pipeline requires; in this example one would call this function with a ViewFormat that has a format of QRhiTexture::RGBA8 and srgb set to false).

This setting is only taken into account when the QRhi::TextureViewFormat feature is reported as supported.

This function was introduced in Qt 6.8.

See also writeViewFormat().

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

Returns the view format used when writing to the texture and when using it with image load/store. When not called, the view format is assumed to be the same as format().

This function was introduced in Qt 6.8.

See also setWriteViewFormat().