PySide6.QtGui.QRhiTexture

class QRhiTexture

Texture resource. More…

Inheritance diagram of PySide6.QtGui.QRhiTexture

Added in version 6.6.

Synopsis

Methods

Virtual methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

A QRhiTexture encapsulates a native texture object, such as a VkImage or MTLTexture.

A QRhiTexture instance is always created by calling the QRhi's newTexture() function . This creates no native graphics resources. To do that, call create() after setting the appropriate options, such as the format and size, although in most cases these are already set based on the arguments passed to newTexture() .

Setting the flags correctly is essential, otherwise various errors can occur depending on the underlying QRhi backend and graphics API. For example, when a texture will be rendered into from a render pass via QRhiTextureRenderTarget , the texture must be created with the RenderTarget flag set. Similarly, when the texture is going to be read back , the UsedAsTransferSource flag must be set upfront. Mipmapped textures must have the MipMapped flag set. And so on. It is not possible to change the flags once create() has succeeded. To release the existing and create a new native texture object with the changed settings, call the setters and call create() again. This then might be a potentially expensive operation.

Example usage

To create a 2D texture with a size of 512x512 pixels and set its contents to all green:

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

Common patterns

A call to create() destroys any existing native resources if create() was successfully called before. If those native resources are still in use by an in-flight frame (i.e., there’s a chance they are still read by the GPU), the destroying of those resources is deferred automatically. Thus a very common and convenient pattern to safely change the size of an already existing texture is the following. In practice this drops and creates a whole new native texture resource underneath, so it is not necessarily a cheap operation, but is more convenient and still faster than the alternatives, because by not destroying the texture object itself, all references to it stay valid in other data structures (e.g., in any QShaderResourceBinding the QRhiTexture is referenced from).

// 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

Note

This is a RHI API with limited compatibility guarantees, see QRhi for details.

See also

QRhiResourceUpdateBatch QRhi QRhiTextureRenderTarget

class Flag

(inherits enum.Flag) Flag values to specify how the texture is going to be used. Not honoring the flags set before create() and attempting to use the texture in ways that was not declared upfront can lead to unspecified behavior or decreased performance depending on the backend and the underlying graphics API.

Constant

Description

QRhiTexture.RenderTarget

The texture going to be used in combination with QRhiTextureRenderTarget .

QRhiTexture.CubeMap

The texture is a cubemap. Such textures have 6 layers, one for each face in the order of +X, -X, +Y, -Y, +Z, -Z. Cubemap textures cannot be multisample.

QRhiTexture.MipMapped

The texture has mipmaps. The appropriate mip count is calculated automatically and can also be retrieved via mipLevelsForSize() . The images for the mip levels have to be provided in the texture uploaded or generated via generateMips() . Multisample textures cannot have mipmaps.

QRhiTexture.sRGB

Use an sRGB format.

QRhiTexture.UsedAsTransferSource

The texture is used as the source of a texture copy or readback, meaning the texture is given as the source in copyTexture() or readBackTexture() .

QRhiTexture.UsedWithGenerateMips

The texture is going to be used with generateMips() .

QRhiTexture.UsedWithLoadStore

The texture is going to be used with image load/store operations, for example, in a compute shader.

QRhiTexture.UsedAsCompressedAtlas

The texture has a compressed format and the dimensions of subresource uploads may not match the texture size.

QRhiTexture.ExternalOES

The texture should use the GL_TEXTURE_EXTERNAL_OES target with OpenGL. This flag is ignored with other graphics APIs.

QRhiTexture.ThreeDimensional

The texture is a 3D texture. Such textures should be created with the newTexture() overload taking a depth in addition to width and height. A 3D texture can have mipmaps but cannot be multisample. When rendering into, or uploading data to a 3D texture, the layer specified in the render target’s color attachment or the upload description refers to a single slice in range [0..depth-1]. The underlying graphics API may not support 3D textures at run time. Support is indicated by the ThreeDimensionalTextures feature.

QRhiTexture.TextureRectangleGL

The texture should use the GL_TEXTURE_RECTANGLE target with OpenGL. This flag is ignored with other graphics APIs. Just like ExternalOES, this flag is useful when working with platform APIs where native OpenGL texture objects received from the platform are wrapped in a QRhiTexture , and the platform can only provide textures for a non-2D texture target.

QRhiTexture.TextureArray

The texture is a texture array, i.e. a single texture object that is a homogeneous array of 2D textures. Texture arrays are created with newTextureArray() . The underlying graphics API may not support texture array objects at run time. Support is indicated by the TextureArrays feature. When rendering into, or uploading data to a texture array, the layer specified in the render target’s color attachment or the upload description selects a single element in the array.

QRhiTexture.OneDimensional

The texture is a 1D texture. Such textures can be created by passing a 0 height and depth to newTexture() . Note that there can be limitations on one dimensional textures depending on the underlying graphics API. For example, rendering to them or using them with mipmap-based filtering may be unsupported. This is indicated by the OneDimensionalTextures and OneDimensionalTextureMipmaps feature flags.

QRhiTexture.UsedAsShadingRateMap
class Format

Specifies the texture format. See also isTextureFormatSupported() and note that flags() can modify the format when sRGB is set.

Constant

Description

QRhiTexture.UnknownFormat

Not a valid format. This cannot be passed to setFormat() .

QRhiTexture.RGBA8

Four components, unsigned normalized 8-bit per component. Always supported. (32 bits total)

QRhiTexture.BGRA8

Four components, unsigned normalized 8-bit per component. (32 bits total)

QRhiTexture.R8

One component, unsigned normalized 8-bit. (8 bits total)

QRhiTexture.RG8

Two components, unsigned normalized 8-bit. (16 bits total)

QRhiTexture.R16

One component, unsigned normalized 16-bit. (16 bits total)

QRhiTexture.RG16

Two components, unsigned normalized 16-bit. (32 bits total)

QRhiTexture.RED_OR_ALPHA8

Either same as R8, or is a similar format with the component swizzled to alpha, depending on RedOrAlpha8IsRed . (8 bits total)

QRhiTexture.RGBA16F

Four components, 16-bit float. (64 bits total)

QRhiTexture.RGBA32F

Four components, 32-bit float. (128 bits total)

QRhiTexture.R16F

One component, 16-bit float. (16 bits total)

QRhiTexture.R32F

One component, 32-bit float. (32 bits total)

QRhiTexture.RGB10A2

Four components, unsigned normalized 10 bit R, G, and B, 2-bit alpha. This is a packed format so native endianness applies. Note that there is no BGR10A2. This is because RGB10A2 maps to DXGI_FORMAT_R10G10B10A2_UNORM with D3D, MTLPixelFormatRGB10A2Unorm with Metal, VK_FORMAT_A2B10G10R10_UNORM_PACK32 with Vulkan, and GL_RGB10_A2/GL_RGB/GL_UNSIGNED_INT_2_10_10_10_REV on OpenGL (ES). This is the only universally supported RGB30 option. The corresponding QImage formats are Format_BGR30 and Format_A2BGR30_Premultiplied . (32 bits total)

QRhiTexture.D16

16-bit depth (normalized unsigned integer)

QRhiTexture.D24

24-bit depth (normalized unsigned integer)

QRhiTexture.D24S8

24-bit depth (normalized unsigned integer), 8 bit stencil

QRhiTexture.D32F

32-bit depth (32-bit float)

QRhiTexture.D32FS8

32-bit depth (32-bit float), 8 bits of stencil, 24 bits unused (64 bits total)

QRhiTexture.BC1

QRhiTexture.BC2

QRhiTexture.BC3

QRhiTexture.BC4

QRhiTexture.BC5

QRhiTexture.BC6H

QRhiTexture.BC7

QRhiTexture.ETC2_RGB8

QRhiTexture.ETC2_RGB8A1

QRhiTexture.ETC2_RGBA8

QRhiTexture.ASTC_4x4

QRhiTexture.ASTC_5x4

QRhiTexture.ASTC_5x5

QRhiTexture.ASTC_6x5

QRhiTexture.ASTC_6x6

QRhiTexture.ASTC_8x5

QRhiTexture.ASTC_8x6

QRhiTexture.ASTC_8x8

QRhiTexture.ASTC_10x5

QRhiTexture.ASTC_10x6

QRhiTexture.ASTC_10x8

QRhiTexture.ASTC_10x10

QRhiTexture.ASTC_12x10

QRhiTexture.ASTC_12x12

QRhiTexture.R8UI

One component, unsigned 8-bit. (8 bits total)

QRhiTexture.R32UI

One component, unsigned 32-bit. (32 bits total)

QRhiTexture.RG32UI

Two components, unsigned 32-bit. (64 bits total)

QRhiTexture.RGBA32UI

Four components, unsigned 32-bit. (128 bits total)

QRhiTexture.R8SI

One component, signed 8-bit. (8 bits total)

QRhiTexture.R32SI

One component, signed 32-bit. (32 bits total)

QRhiTexture.RG32SI

Two components, signed 32-bit. (64 bits total)

QRhiTexture.RGBA32SI

Four components, signed 32-bit. (128 bits total)
PySide6.QtGui.QRhiTexture.m_format
PySide6.QtGui.QRhiTexture.m_pixelSize
PySide6.QtGui.QRhiTexture.m_depth
PySide6.QtGui.QRhiTexture.m_arraySize
PySide6.QtGui.QRhiTexture.m_sampleCount
PySide6.QtGui.QRhiTexture.m_flags
PySide6.QtGui.QRhiTexture.m_arrayRangeStart
PySide6.QtGui.QRhiTexture.m_arrayRangeLength
PySide6.QtGui.QRhiTexture.m_readViewFormat
PySide6.QtGui.QRhiTexture.m_writeViewFormat
arrayRangeLength()
Return type:

int

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

See also

setArrayRange()

arrayRangeStart()
Return type:

int

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

See also

setArrayRange()

arraySize()
Return type:

int

Returns the texture array size.

See also

setArraySize()

abstract create()
Return type:

bool

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.

depth()
Return type:

int

Returns the depth for 3D textures.

See also

setDepth()

flags()
Return type:

Combination of Flag

Returns the texture flags.

See also

setFlags()

format()
Return type:

Format

Returns the texture format.

See also

setFormat()

pixelSize()
Return type:

QSize

Returns the size in pixels.

See also

setPixelSize()

readViewFormat()
Return type:

ViewFormat

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

sampleCount()
Return type:

int

Returns the sample count. 1 means no multisample antialiasing.

See also

setSampleCount()

setArrayRange(startIndex, count)
Parameters:

  • startIndex – int

  • count – int

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

setArraySize(arraySize)
Parameters:

arraySize – int

Sets the texture arraySize.

See also

arraySize()

setDepth(depth)
Parameters:

depth – int

Sets the depth for a 3D texture.

See also

depth()

setFlags(f)
Parameters:

f – Combination of Flag

Sets the texture flags to f.

See also

flags()

setFormat(fmt)
Parameters:

fmt – Format

Sets the requested texture format to fmt.

Note

The value set is only taken into account upon the next call to create() , i.e. when the underlying graphics resource are (re)created. Setting a new value is futile otherwise and must be avoided since it can lead to inconsistent state.

See also

format()

setNativeLayout(layout)
Parameters:

layout – int

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 beginExternal() and 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 endExternal() and before a subsequent beginPass() .

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

Note

With Vulkan layout is a VkImageLayout. With Direct 3D 12 layout is a value composed of the bits from D3D12_RESOURCE_STATES.

setPixelSize(sz)
Parameters:

sz – QSize

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

Note

The value set is only taken into account upon the next call to create() , i.e. when the underlying graphics resource are (re)created. Setting a new value is futile otherwise and must be avoided since it can lead to inconsistent state. The same applies to all other setters as well.

See also

pixelSize()

setReadViewFormat(fmt)
Parameters:

fmt – ViewFormat

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 TextureViewFormat feature is reported as supported.

Note

This functionality is provided to allow “casting” between non-sRGB and sRGB in order to get the shader reads perform, or not perform, the implicit sRGB conversions. Other types of casting may or may not be functional.

See also

readViewFormat()

setSampleCount(s)
Parameters:

s – int

Sets the sample count to s.

See also

sampleCount()

setWriteViewFormat(fmt)
Parameters:

fmt – ViewFormat

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 RGBA8 and srgb set to false).

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

Note

This functionality is provided to allow “casting” between non-sRGB and sRGB in order to get the shader write not perform, or perform, the implicit sRGB conversions. Other types of casting may or may not be functional.

See also

writeViewFormat()

writeViewFormat()
Return type:

ViewFormat

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

class ViewFormat

Specifies the view format for reading or writing from or to the texture.

Details

Note

This is a RHI API with limited compatibility guarantees, see QRhi for details.

Added in version 6.8.

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

PySide6.QtGui.QRhiTexture.ViewFormat.format
PySide6.QtGui.QRhiTexture.ViewFormat.srgb