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().

[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().

void QRhiTexture::setSampleCount(int s)

Sets the sample count to s.

See also sampleCount().